Help file for MacAnova 4.13
(C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005
    by Gary W. Oehlert and Christopher Bingham
Updated 20041115 CB

This is the help file describing all MacAnova commands and most of the
pre-defined macros.  It is opened and read at start up and the "message"
of the day near its start is printed.

See below for a description of the format of a MacAnova help file.

!!!! Starting marker for message of the day
There are enhanced capabilities for working with complex data.  These
include functions cdivc(), cdivcj(), hdivh(), and hdivhj() for
elementwise division and macros cdiag(), ceigen(), cjtranspose(),
cmatmultc(), csolve(), csubscr(), ctrace() and ctranspose()
Type 'help(updates_412)' and 'help(updates_413)' for a summary of
changes from release  of Version 4.12
!!!! Ending marker for message of the day

???? Starting marker for list of up to 32 comma/newline separated keys
ANOVA
Categorical Data
CHARACTER Variables
Combining Variables
Comparisons
Complex Arithmetic
Confidence Intervals
Control
Descriptive Statistics
Files
GLM
General
Input
LOGICAL Variables
NULL Variables
Macros
Matrix Algebra
Missing Values
Multivariate Analysis
Operations
Ordering
Output
Plotting
Probabilities
Random Numbers
Regression
Residuals
Structures
Syntax
Time Series
Transformations
Variables
???? Ending marker for keys

Note: There are no topics with names longer than 15 characters so as to
allow 5 column output from 'help()' with width >= 80.

This file is read by commands help() and usage().  It has the format
described below.  The same format is used for help that follows a
   _E_N_D_O_F_M_A_C_R_O_S_
line in a file of macros.

                 Format of a MacAnova Help File

A MacAnova help file has some or all of the following elements.

Message of the day
  A message of the day to be printed at start up consists of the lines
  between two lines starting with '!!!!' before the help topics
  themselves at the start of the file.  This is recognized only in the
  default help file, usually this file.

Help keys
  Up to 32 keys may be listed between lines starting '????' before the
  help topics themselves.  They can be separated by commas or end of
  lines.

Help Topics
  Help topics themselves begin with the first line starting '===='.

  Each topic starts with '====topicName' in column 1, followed by an
  unlimited number of lines of information.  It is helpful, but not
  required, that topics be in alphabetical order.

  The information may include Usage lines and regular help lines, the
  latter usually subdivided into subtopics.

  It is no longer the case that topic names longer than 12 characters
  must be quoted as arguments to help().  However, topic names longer
  than 15 characters are discouraged.  If topics have 10 characters or
  fewer, their subtopics can be accessed similarly to
  'help(shortTopic:"subtopic_name")'.  Subtopics of topics with longer
  names must be accessed by
  'help(longerTopic,subtopic:"subtopic_name")'.

  Each topic name that refers to a function or a pre-defined macro has
  '()' appended to it.  This does not affect output but helps in
  automatic generation of the MacAnova Reference Manual from help files.

  Names of topics that are not to be included in the Reference Manual
  are followed by '*'.  This does not affect help() output.

  Names of topics whose usage lines are to be omitted from the Reference
  Manual are followed by '%'.  This does not affect help() output.

  The convention is used that when referring to functions and macros by
  name in help topics, '()' is appended to the name.

  Lines for usage()
  If the next line after '====topicName' starts with '%%%%', all
  following lines up to a matching '%%%%' are skipped by help() but are
  printed by usage().  usage() skips the lines following the second
  '%%%%'.

  Subtopics
  As of 001207, topics may have subtopics indicated by lines starting
    @@@@subtopic_name
  You ask for help on a subtopic of a help topic by, for example,
    Cmd> help(options:"format") # help on subtopic 'format' of 'options'

  Subtopic names can be no longer than 50 alphanumeric characters plus
  '.', '_' and '-'.  Case is ignored by help() and a match is found if
  the supplied subtopic name matches the start of the subtopic name.

  If the name is followed by '#' or '%', the remainder of the line is
  interpreted as a title to be printed centered ('#') or left justified
  ('%'), for example
    @@@@see_also#Cross references

  A subtopic title can be no longer than 72 characters.

  Use
    @@@@______
  to end a subtopic that is not immediately followed by another
  subtopic.

  Keys
  Keys separated by commas can follow the topic name (and trailing '()',
  '*' or '%') if separated from it by '#'.  These should be selected
  from up to 32 keys listed between lines starting with '????' somewhere
  before the first help topic.  Case is ignored.  However, it is
  important that, except for case, the key exactly match one of the
  keys listed before the help topics.

  News topic
  It is recommended that any public help file have a topic 'news' where
  information about changes in the associated macro file can be
  recorded.  News items should be in reverse chronological order with
  each item starting with a date of the form yymmdd (e.g., 010901) or
  yyyymmdd (for example, 20010901).

End-of-macros line
  Help can be appended to a file of macros or data.  It should be
  separated from the macros and/or data by a line starting
     _E_N_D_O_F_M_A_C_R_O_S_

End-of-file line
  The file should be terminated by a line starting '_E_O_F_'

====abs()#transformations
%%%%
abs(x), x REAL or a structure with REAL components
%%%%
@@@@usage#Usage
abs(x) returns the absolute values of the elements of x, when x is a
REAL scalar, vector, matrix or array.  The result has the same shape as
x.

When any element of x is MISSING, so is the corresponding element of
abs(x) and a warning message is printed.

@@@@structure_argument #Structure argument
When x is a structure, all of whose non-structure components are REAL,
abs(x) is a structure of the same shape and with the same component
names as x, with each non-structure component transformed by abs().

@@@@see_also#Cross reference
See topic 'transformations' for more information on abs().
@@@@______

====acos()#transformations
%%%%
acos(x [, degrees:T or radians:T or cycles:T]), x REAL or a structure
  with REAL components value in radians (default), cycles, or degrees as
  specified by option "angles" or the optional keyword
%%%%
@@@@usage# Usage
acos(x) computes the inverse cosines of the elements of x, where x is a
REAL scalar, vector, matrix or array.  The result has the same shape as
x.  cos(acos(x)) should be the same as x except for rounding error.

The units of the result are radians, degrees or cycles as determined by
the value of option 'angles'.  The default is radians.  See subtopic
'options:"angles"'.

acos(x, radians:T), acos(x, degrees:T), acos(x, cycles:T) return results
in the indicated units, regardless of the value of option 'angles'.

When any element of x is MISSING or is above 1 or below -1, the
corresponding element of the result is MISSING and a warning message is
printed.

@@@@structure_argument #Structure argument
When x is a structure, all of whose non-structure components are REAL,
acos(x [,UNITS:T]), where UNITS is one of 'radians', 'degrees' or
'cycles', is a structure of the same shape and with the same component
names as x with each non-structure component transformed by acos().

@@@@examples#Example
  Cmd> vector(acos(.5),acos(.5,degrees:T),acos(.5,cycles:T))
  (1)      1.0472          60     0.16667

@@@@see_also#Cross reference
See topic 'transformations' for more information on acos(), including
its use with a CHARACTER argument.
@@@@______

====addchars()#plotting
%%%%
addchars([Graph,] x,y [,symbols:c] [,lines:T,impulse:T]\
  [, graphics keyword phrases])
addchars([Graph] [,x,y [,symbols:c]], keys:str), str a structure whose
  components names match graphics keywords.
%%%%
@@@@usage#Usage
addchars(x,y,symbols:c) is equivalent to chplot(x,y,symbols:c,add:T).
It adds character labeled points to the plot in LASTPLOT, displays the
plot, and updates LASTPLOT with the new information.  For compatibility
with past versions, the use of keyword 'symbols' is optional.

Arguments x, y, and c are as for chplot() and the points are labeled the
same way as is done by chplot().  When 'symbols:c' is omitted, the same
default is used as for chplot().  It is not an error when x or y is
NULL; a warning message is printed and no plotting occurs.

It is an error if LASTPLOT does not exist.

Whenever LASTPLOT is updated, the appropriate component of GRAPHWINDOWS
is made identical to LASTPLOT.  See topic 'GRAPHWINDOWS'.

@@@@graph_variable_argument#Graph Variable Argument
addchars(Graph,x,y,symbols:c) or chplot(Graph,x,y,symbols.c,add:T)
displays GRAPH variable Graph with the addition of character labeled
points, saving the modified plot in LASTPLOT.  Graph is not changed
(unless it is LASTPLOT).

@@@@keep_and_show_keywords#Keywords 'keep' and 'show'
addchars(x,y,symbols:c,keep:F) suppresses any change to LASTPLOT.  The
appropriate element of GRAPHWINDOWS is set to NULL.

addchars(x,y,symbols:c,show:F) suppresses immediate display of the
modified graph or change to GRAPHWINDOWS but updates LASTPLOT.  This is
useful when you are building a complex graph in stages using addchars(),
addlines(), addstrings(), or addpoints().  When you are done, simply
type showplot().  You can't use both show:F and keep:F.

@@@@keywords#Keywords
Keywords 'dumb', 'lines', 'linetype', 'thickness', 'impulse', 'xmin',
'xmax', 'ymin', 'ymax', 'logx', 'logy', 'xlab', 'ylab', 'title',
'xaxis', 'yaxis', 'borders', 'ticks', 'xticks', 'yticks', 'xticklen',
'yticklen', 'xticklabs', 'yticklabs', 'height', 'width', 'pause',
'silent' and 'notes' may be used as for other plotting commands.  See
topics 'graph_keys', 'graph_border' and 'graph_keys'

@@@@keys_keyword#Keyword 'keys'
addchars([Graph,] keys:structure(x:x,y:y,symbols:c [other keyword
phrases)) is equivalent to addchars([Graph,] x,y,symbols:c [other
keyword phrases]).  See topic 'graph_keys' for details.
@@@@______

When option 'dumbplot' has been set False (see subtopic
'options:"dumbplot"'), the plot will be a low resolution plot unless
'dumb:F' is an argument.

@@@@missing_value_for_xmin_xmax_ymin_ymax#Missing value for 'xmin', 'xmax', 'ymin' and 'ymax'
A value of MISSING for any of xmin, xmax, ymin or ymax (for example,
xmin:?) forces determination of an extreme value from the current data
and data already in the graph.

@@@@keyword_use#Keyword Use
New labels and title may be set only by keywords 'xlab', 'ylab' and
'title'.  That is addchars(newx:x, newy:y,symbols:c) has no effect on
the axis labels of the graph being modified.

addchars(x,y,symbols:c,add:F, ...) is equivalent to chplot(x,y,
symbols:c, ...) except that LASTPLOT must be defined.

@@@@see_also#Cross references
See topic 'graph_assign' for information on another way to add data and
other information to a plot.

See topic 'graphs' for general information on plots and on variable
LASTPLOT.  See topic 'graph_keys' for information on keywords.  See
topic 'graph_files' for information on writing a graph to a file.
@@@@______

====addhelpfile()#general,files
%%%%
addhelpfile(names [,T]), names a CHARACTER scalar or vector of length 2
%%%%
@@@@usage#Usage
addhelpfile(fileName) adds fileName at the beginning of CHARACTER vector
HELPFILES which contains the names of files to be searched for help.
fileName must be a quoted string or CHARACTER scalar.  Because fileName
is added at the beginning of HELPFILES, the file will usually be the
first one searched.  In addition, the name "index" is added at the start
of CHARACTER vector HELPINDICES.

addhelpfile(fileName,T) does the same except the file name is added at
the end of HELPFILES so the file will be searched last.  "index" is
added at the end of HELPINDICES.

addhelpfile(vector(fileName,indexName) [,T]) does the same, except
that CHARACTER scalar indexName is added at the start or end of
HELPINDICES instead of "index".

When HELPFILES does not already exist, addhelpfile() creates it.

@@@@directories_searched#Directories searched
When fileName is a simple file name containing no directory or folder
information (for example, "survival.hlp" but not "./survival.hlp" or
":survival.hlp"), the file is first assumed to be in the default
directory.  If not found there, MacAnova looks for it in the folders or
directories listed in variable DATAPATHS. See topics 'DATAPATHS',
adddatapath(), 'file_names', 'files'.

@@@@windowed_versions#Windowed versions
On Windowed versions of MacAnova, you may combine addhelpfile() with
getfilename() to choose the file interactively;  for example,
addhelpfile(getfilename() [,T])    This will include the complete
path name (file name with directory information) of the selected
file in HELPFILES.  

@@@@examples#Examples
Example:
  Cmd> addhelpfile(vector("survival.hlp","survival_index"))
  Cmd> addhelpfile("C:/mvmacros/survival.hlp",T) # for DOS/Windows
  Cmd> addhelpfile("MyDisk:MVMacros:Survival.hlp",T) # on a Mac
  Cmd> addhelpfile("") # file added to be selected in dialog box

@@@@see_also#Cross references
See also topics help(), gethelp().
@@@@______


====addlines()#plotting
%%%%
addlines([Graph,] x,y [,linetype:PosInt,thickness:PosReal] [,impulse:T]\
   [,other graphics keyword phrases])
addlines([Graph] [,x,y], keys:str), str a structure whose
  components names match graphics keywords.
%%%%
@@@@usage#Usage
addlines(x,y) is equivalent to lineplot(x,y,add:T).  It displays the
plot in LASTPLOT, adding lines such as are produced by lineplot(), and
updates LASTPLOT with the new information.

Arguments x, and y are as for lineplot().  They can be replaced by a
structure with at least two REAL components.  Any components beyond the
first two are ignored.  It is not an error when x or y is NULL; no
plotting occurs.

It is an error if LASTPLOT does not exist.

When 'dumbplot' has been set False (see subtopic 'options:"dumbplot"'),
the plot will be a low resolution plot unless 'dumb:F' is an argument.

@@@@graph_variable_as_argument#Graph variable as argument
addlines(Graph,x,y) or lineplot(Graph,x,y,add:T) displays GRAPH variable
Graph with the addition of lines connecting points specified by x and
y, saving the modified plot in LASTPLOT.  Graph is not changed (unless
it is LASTPLOT).

@@@@keep_and_show_keywords#Keep and show keywords
addlines(x,y,keep:F) (or lineplot(x,y,keep:F,add:T)) suppresses any
change to LASTPLOT.

addlines(x,y,show:F) (or lineplot(x,y,show:F,add:T)) suppresses
immediate display of the modified graph but updates LASTPLOT.  This is
useful when you are building a complex graph in stages using addlines(),
addchars(), addstrings(), or addpoints().  When you are done, simply
type showplot().  You can't use both show:F and keep:F.

@@@@keywords#Keywords
You can use keywords 'linetype' and 'thickness' to control the type of
lines used (solid, dashed, etc.).  See topic 'graph_keys'.

Keywords 'dumb', 'lines', 'impulse', 'xmin', 'xmax', 'ymin', 'ymax',
'logx', 'logy', 'xlab', 'ylab', 'title', 'xaxis', 'yaxis', 'borders',
'ticks', 'xticks', 'yticks', 'xticklen', 'yticklen', 'xticklabs',
'yticklabs', 'height', 'width', 'pause', 'silent' and 'notes' may be
used as for other plotting commands.  See topics 'graph_keys',
'graph_border' and 'graph_ticks'

@@@@keys_keyword#Keyword 'keys'
addlines([Graph,] keys:structure(x:x,y:y [other keyword phrases)) is
equivalent to addlines([Graph,] x:x,y:y [other keyword phrases]).  See
topic 'graph_keys' for details.
@@@@______

A value of MISSING for any of xmin, xmax, ymin or ymax (for example,
xmin:?) forces determination of a value from the current data and data
already in the graph.

New labels and title may be set only by keywords 'xlab', 'ylab' and
'title'.

addlines(x,y,add:F, ...) is equivalent to lineplot(x,y, ...).

@@@@see_also#Cross references
See topic 'graph_assign' for information on another way to add data and
other information to a plot.

See topic 'graphs' for general information on plots and on variable
LASTPLOT.  See topic 'graph_keys' for information on keywords.  See
topic 'graph_files' for information on writing a graph to a file.
@@@@______

====adddatapath()#input,files
%%%%
adddatapath(dirName [,T]), dirName a quoted string or CHARACTER vector
  specifying one or more additional directory or folder names to search
  when attempting to read a file
%%%%
@@@@usage#Usage
adddatapath(DirName) adds DirName at the beginning of CHARACTER vector
DATAPATHS.  DirName must be a quoted string or CHARACTER scalar
specifying the name of a directory or folder.  See topic 'DATAPATHS'.

When commands such as read(), matread(), macroread() and vecread() don't
find a wanted file in the default directory (see 'files'), they search
for it in the folders or directories whose names are in DATAPATHS.
Because DirName is added at the start of DATAPATHS, the folder or
directory will be searched before any other locations in DATAPATHS.

adddatapath(DirName,T) does the same except DirName is added at the end
of DATAPATHS so the directory or folder will be searched last.

For both usages, DirName can also be a CHARACTER vector, each element of
which specifies a directory or folder to be searched.

When DATAPATHS does not already exist, adddatapath(DirName) creates it.

@@@@example#Example
Example:
  Cmd> adddatapath("MyDisk:Survey Folder:") # on Mac OS 9

  Cmd> adddatapath("D:/SURVEY.DIR/") # on DOS/Windows

  Cmd> adddatapath("~/survey.dir") # on Linux/Unix

  Cmd> adddatapath(getfilename(pathonly:T)) # Windowed versions only

The last example adds to DATAPATHS the folder or directory containing
the file selected in a file navigation dialog box.

@@@@see_also#Cross references
See also topics matread(), read(), vecread(), macroread(), inforead(),
getfilename(), 'files'.
@@@@______

====addmacrofile()#macros,files
%%%%
addmacrofile(fileName [,T]), fileName a quoted string or CHARACTER
  vector specifying one or more additional files to be searched by
  getmacros().
%%%%
@@@@usage#Usage
addmacrofile(fileName) adds fileName at the start of CHARACTER vector
MACROFILES which contains the names of files to be searched for macros.
fileName must be a quoted string or CHARACTER scalar.  Because fileName
is added at the startof MACROFILES, the file will be the first one
searched for a macro.

addmacrofile(fileName,T) does the same except the file name is added at
the end of MACROFILES so the file will be searched last.

When fileName is a simple file name containing no directory or folder
information (for example, "mydata.dat" but not "./mydata.dat" or
":mydata.dat"), the file is first assumed to be in the default
directory.  If not found there, MacAnova looks for it in the folders or
directories listed in variable DATAPATHS. See topics 'DATAPATHS',
adddatapath(), 'file_names', 'files', 'macro_files'.

For both usages, fileName can also be a CHARACTER vector, each element
of which specifies a file to be searched.

When MACROFILES does not already exist, addmacrofile(fileName) creates
it.

@@@@windowed_versions#Windowed versions
addmacrofile("" [,T] does the same, except you pick the file
interactively using a file navigation dialog box.  The complete path
name (file name with directory information) of the selected file will be
added to MACROFILES.  This works only in windowed versions.  An
equivalent usage is addmacrofile(getfilename(type:"text") [,T]).  
See getfilename().

If the first argument is a CHARACTER vector, on windowed versions, any
of its elements can be "".

@@@@examples#Examples
Example:
  Cmd> addmacrofile("survival.mac")

  Cmd> addmacrofile("C:/mvmacros/survival.mac",T) # for DOS/Windows

  Cmd> addmacrofile("MyDisk:MVMacros:Survival.mac",T) # on a Mac

  Cmd> addmacrofile("~/mvmacros/survival.mac",T) # on Linux/Unix

  Cmd> addmacrofile("") # file added to be selected in dialog box

@@@@see_also#Cross references
See also topics getfilename(), getmacros(), 'macros'.
@@@@______

====addpoints()#plotting
%%%%
addpoints([Graph,] x,y [,lines:T,impulse:T][, graphics keyword phrases])
addpoints([Graph] [,x,y], keys:str), str a structure whose components
  names match graphics keywords.
%%%%
@@@@usage#Usage
addpoints(x,y) is equivalent to plot(x,y,add:T).  It displays the plot
in LASTPLOT, adding points such as are produced by plot(), and updates
LASTPLOT with the new information.  It is an error if LASTPLOT does not
exist.

Arguments x and y are as in plot().  They can be replaced by a structure
with at least two components.  Any components beyond the first two are
ignored.  It is not an error when x or y is NULL; a warning message is
printed and no plotting occurs.

@@@@graph_variable_as_argument#Graph variable as argument
addpoints(Graph,x,y) displays GRAPH variable Graph with the addition of
points such as are produced by plot(), and saves the plot in LASTPLOT.
Graph is not changed (unless it is LASTPLOT).

@@@@keep_and_show_keywords#Keywords 'keep' and 'show'
addpoints(x,y,keep:F) suppresses any change to LASTPLOT.

addpoints(x,y,show:F) suppresses immediate display of the modified graph
but updates LASTPLOT.  This is useful when you are building a complex
graph in stages using addlines(), addchars(), addstrings(), or
addpoints().  When you are done, simply type showplot().  You can't use
both show:F and keep:F.

@@@@keywords#Keywords
Keywords 'dumb', 'lines', 'linetype', 'thickness', 'impulse', 'xmin',
'xmax', 'ymin', 'ymax', 'logx', 'logy', 'xlab', 'ylab', 'title',
'xaxis', 'yaxis', 'borders', 'ticks', 'xticks', 'yticks', 'xticklen',
'yticklen', 'xticklabs', 'yticklabs', 'height', 'width', 'pause',
'silent' and 'notes' may be used as for other plotting commands.  See
topics 'graph_keys', 'graph_border' and 'graph_ticks'

@@@@keys_keyword#Keyword 'keys'
addpoints([Graph,] keys:structure(x:x,y:y [other keyword phrases)) is
equivalent to addpoints([Graph,] x:x,y:y [other keyword phrases]).  See
topic 'graph_keys' for details.

@@@@determination_of_extremes#Determination of extremes
A value of MISSING for any of xmin, xmax, ymin or ymax (for example,
xmin:?) forces determination of a value from the current data and data
already in the graph.

@@@@keyword_use#Keyword use
New labels and title may be set only by keywords 'xlab', 'ylab' and
'title'.

addpoints(x,y,add:F, ...) is equivalent to plot(x,y, ...).

@@@@see_also#Cross references
See topic 'graph_assign' for information on another way to add data and
other information to a plot.

See topic 'graphs' for general information on plots and on variable
LASTPLOT.  See topic 'graph_keys' for information on keywords.  See
topic 'graph_files' for information on writing a graph to a file.
@@@@______

====addstrings()#plotting
%%%%
addstrings([Graph,] x,y, strings:charVec,[, graphics keyword phrases])
addstrings([Graph,] [x,y, strings:charVec],keys:str), str a structure
  whose component names are graphics keywords
%%%%
@@@@usage#Usage
addstrings(x,y,strings:charVec) displays the plot in LASTPLOT and then
writes the i-th element of CHARACTER vector charVec at position (x[i],
y[i]), updating LASTPLOT to include the new information.  It is
completely equivalent to stringplot(x,y,strings:charVec,add:T).

It is not an error when x or y is NULL; a warning message is printed and
no plotting occurs.

For backward compatibility with earlier versions, keyword 'strings' can
be omitted (addstrings(x,y,charVec)).

When option 'dumbplot' has been set False (see subtopic
'options:"dumbplot"'), the plot will be a low resolution plot unless
'dumb:F' is an argument.

@@@@graph_variable_as_argument#Graph variable as argument
addstrings(Graph,x,y,strings:charVec), displays GRAPH variable Graph,
adding the string or strings in charVec, and saves the modified plot in
LASTPLOT.  Graph is not changed (unless it is LASTPLOT).

@@@@limitations_on_x_and_y#Limitations on x and y
In contrast with other plotting commands, non-NULL x and y must both be
vectors of the same length.  The most usual use is when both x and y are
REAL scalars and charVec is a quoted string or CHARACTER scalar to be
written at coordinates (x,y).  A typical usage would be
  Cmd> addstrings(110,20,strings:"Frequency 1 cycle/week")).

@@@@justify_keyword#Keyword 'justify'
By default, each string is written centered at (x[i], y[i]).  However,
if 'justify:"l"' or 'justify:"r"' is an argument following charVec, each
string will be left or right justified.

@@@@keep_and_show_keywords#Keywords 'keep' and 'show'
addstrings(x,y,strings:charVec,keep:F) suppresses any change to
LASTPLOT.

addstrings(x,y,strings:charVec,show:F) suppresses immediate display of
the modified graph but updates LASTPLOT.  This is useful when you are
building a complex graph in stages using addlines(), addchars(),
addpoints(), or addstrings().  When you are done, simply type
showplot().  You can't use both show:F and keep:F.

@@@@keywords#Keywords
Keywords 'dumb', 'xmin', 'xmax', 'ymin', 'ymax', 'logx', 'logy', 'xlab',
'ylab', 'title', 'xaxis', 'yaxis', 'borders', 'ticks', 'xticks',
'yticks', 'xticklen', 'yticklen', 'xticklabs', 'yticklabs', 'height',
'width', 'pause', 'silent' and 'notes' may be used as for other plotting
commands.  See topics 'graph_keys', 'graph_border' and 'graph_keys'.
Keywords 'impulse' and 'lines' are ignored.

@@@@keys_keyword#Keyword 'keys'
addstrings([Graph,] keys:structure(x:x,y:y,strings:charVec [other
keyword phrases)) is equivalent to addstrings([Graph,] x:x,y:y,
strings:charVec [other keyword phrases]).  See topic 'graph_keys' for
details.

@@@@determining_extremes#Determining extremes
A value of MISSING for any of xmin, xmax, ymin or ymax (for example,
xmin:?) forces determination of a value from the current data and data
already in the graph.

@@@@keyword_use#Keyword use
New labels and title may be set only by keywords 'xlab', 'ylab' and
'title'.

addstrings(x,y,strings:s,add:F, ...) is equivalent to stringplot(x,y,
strings:s, ...).

@@@@see_also#Cross references
See topic 'graphs' for general information on plots and on variable
LASTPLOT.  See topic 'graph_keys' for information on keywords.  See
topic 'graph_files' for information on writing a graph to a file.
@@@@______

====alltrue()#logical variables,syntax
%%%%
alltrue(arg1,arg2,...,argm), all arguments LOGICAL scalars
%%%%
@@@@usage#Usage
alltrue(a1,a2,...,aM) is equivalent to a1 && a2 && ... && aM, except
that no arguments are evaluated unnecessarily, that is, it evaluates no
arguments after the first false one.  All arguments must be LOGICAL
scalars.

@@@@example#Example
Example:
   if(!alltrue(isscalar(x,real:T),x > 0, x == floor(x))){
      error("x is not positive integer")
   }

The apparently more natural way to do the same thing
   if(!(isscalar(x,real:T) && x > 0 && x == floor(x))){
      error("x is not positive integer")
   }
would not do what you want for a non-REAL x since an attempt would be
made to evaluate floor(x), which is illegal for non-REALs.

@@@@see_also#Cross references
See also topics 'logic', anytrue().
@@@@______

====anova()#glm,anova
%%%%
anova([Model] [,print:F or silent:T,fstats:T,pvals:T,coefs:F,\
   unbalanced:T, marginal:T])
%%%%
@@@@usage#Usage
anova(Model) computes and prints an ANOVA table for the linear model in
the CHARACTER variable Model.

@@@@examples_1#Examples
Examples (y a REAL vector, a and b factors, x a variate):
   anova("y = a")                    One-way ANOVA of y
   anova("y = a+b")                  Two-way ANOVA of y with no
                                     interaction
   anova("y = x+a+b+a.b")            Two-way analysis of covariance of
                                     y with interaction and covariate x
   anova("{log10(y)} = {sqrt(x)}+a") One-way analysis of covariance of
                                     log10(y) with covariate sqrt(x)

All variables referred to in Model must be REAL vectors or factors and
have the same lengths.

See topic 'models' for more information on how to specify Model.

@@@@weights#Weights
anova(Model,weights:Wts) does an analysis using weighted least squares.
Wts must be a REAL vector with no negative elements, with the same
length as the response vector.  You can abbreviate 'weights:Wts' to
'wts:Wts'.

@@@@omitting_model#Omitting model
When you omit Model (anova() or anova(,...)), the model used by the most
recent GLM command such as anova(), regress() or poisson() is used.

When the previous GLM command was regress(), no new computations are
done.  The ANOVA table is based on what was previously computed.

When there haven't been previous GLM commands, but CHARACTER variable
STRMODEL exists, anova() uses STRMODEL as Model.

@@@@side_effect_variables_created#Side effect variables created
Side effect variables created are RESIDUALS, HII, DF, SS, DEPVNAME,
TERMNAMES, and STRMODEL.

When weights are specified, RESIDUALS = Response - Fitted and
WTDRESIDUALS = sqrt(Wts)*RESIDUALS is an additional side effect vector.
You should use WTDRESIDUALS rather than RESIDUALS in residual plots or
other diagnostic procedures.

@@@@keywords#Keywords
Other keyword phrases that can be used with anova() are 'unbalanced:T',
'print:T', 'silent:T', 'fstats:T', 'pvals:T', 'coefs:F' and marginal:T'.
See topic 'glm_keys' for details.  See 'options' for information on
changing the default values of 'fstats' and 'pvals'.

@@@@balanced_designs#Balanced designs
No design with MISSING values, weights or non-factor variables is ever
considered to be balanced.  This is true, even when all the weights are
1 and the non-MISSING values make up a balanced design.

Otherwise MacAnova recognizes balance in only two cases:
  (1) The design is completely balanced, that is, all cells have the
  same number of cases.
  (2) The design is a balanced main effect design such as a Latin
  square.

In these cases, computations are done by a fast method which uses
marginal totals, quite analogous to the usual hand computations for a
balanced analysis of variance.  Otherwise, the analysis is done by
explicitly constructing the design matrix and doing modified Gram-
Schmidt orthogonalization.

You can force an unbalanced computation for balanced data by
'unbalanced:T'.

@@@@nonbalanced_designs#Nonbalanced designs
For non-balanced designs or with 'unbalanced:T', unless 'marginal:T' is
an argument, sums of squares are computed sequentially and an advisory
message to that effect is printed.

This means that, in an unbalanced ANOVA, to get all the sums of squares
useful for testing hypotheses, you may need to run anova() several
times, with the terms in the model in different orders.  For example,
the A main effect sum of squares in a two way unbalanced ANOVA is the
sum of squares for 'a' from anova("y=b+a") and the B main effect sum of
squares is the sum of squares for 'b' from anova("y=a+b").

In many cases, use of 'marginal:T' can simplify things.  For example the
A and B sums of squares produced by anova("y=a+b",marginal:T) are the A
sums of squares from anova("y=b+a") and the B sums of squares from
anova("y=a+b").

@@@@after_regress#After regress()
When the previous GLM command was regress() the behavior of anova() with
Model missing is slightly modified -- it uses the results from the
previous computation instead of computing things afresh, even if the
variables in the previous model have been changed or deleted.
Specifically, any factors in the model are treated as variates (with 1
degree of freedom) and, if the previous GLM command was regress() with
weights specified by keyword 'weights' or 'wts', the entries in the
ANOVA table pertain to the weighted regression.

For example, even when a, b, and c are factors, the commands

  Cmd> regress("y=a+b+c",weights:w); anova()

print a summary of the weighted multiple regression, followed by an
weighted regression ANOVA table with 1 degree of freedom for each of a,
b and c.  This is different from anova("y=a+b+c") which computes an
unweighted factorial ANOVA with no interactions.

@@@@see_also#Cross references
See also coefs(), cellstats(), contrast(), factor(), fastanova(),
modelinfo(), predtable(), regress(), secoefs(), xvariables().
@@@@______

====anovapred()#glm,anova
%%%%
anovapred(a,b,...), a, b, ... all the factors in STRMODEL
%%%%
@@@@usage#Usage
anovapred(a,b,...), where a, b, ... are all the factors in the most
recent GLM model, computes the fitted (predicted) value, the standard
error of estimation, and the standard error of prediction for each
cell. The result is a structure with components 'estimate', 'SEest' and
'SEpred', each of which is a vector, matrix, or array with dimensions
derived from the number of levels of a, b, ....  It uses side effect
variables DEPVNAME, RESIDUALS, and HII.

When the most recent GLM model was manova() with a p-dimensional
dependent variable, each component will have an extra dimension of size
p.

When the most recent GLM model included variates (non-factors), or when
you do not include all factors in the argument list, the results will
probably be wrong, although no warning message will be printed.
@@@@______

anovapred() is implemented as a pre-defined macro.

@@@@see_also#Cross references
See also predtable(), regpred(), 'glm'.
@@@@______

====anymissing()#missing values,null variables
%%%%
anymissing(x), x REAL, LOGICAL, or CHARACTER, returns True or False
%%%%
@@@@usage#Usage
anymissing(x) returns the value True if x contains any missing values
and the value False otherwise.  x must be a vector, matrix, or array.
When x is CHAR, anymissing(x) is True if and only if any string in x is
empty ("").

When x is a NULL variable, anymissing(x) returns the value False.

anymissing(Str), where Str is a structure, returns a structure whose
non-structure components parallel those of Str, but are LOGICAL scalars,
indicating whether the corresponding component of Str contains any
missing values.  To test whether any component of a structure Str
contains any missing values, use if(sum(vector(anymissing(Str))) !=
0){...}.

@@@@examples#Examples
Examples:
  Cmd> vector(anymissing(vector(1,5,?)),anymissing(vector("A","B","")))
  (1) T       T

  Cmd> vector(anymissing(vector(1,5,7)),anymissing(vector("A","B","C")))
  (1) F       F

  Cmd> anymissing(structure(a1:vector(1,5,?),a2:vector("A","B","C")))
  component: a1
  (1) T
  component: a2
  (1) F

@@@@see_also#Cross references
See also topics ismissing(), 'NULL'.
@@@@______

====anytrue()#logical variables,syntax
%%%%
anytrue(arg1,arg2,...,argM), all arguments LOGICAL scalars
%%%%
@@@@usage#Usage
anytrue(a1,a2,...,aM) is equivalent to a1 || a2 || ... || aM, except
that no arguments are evaluated unnecessarily, that is, it evaluates no
arguments after the first true one.  All arguments must be LOGICAL
scalars.

@@@@example#Example
Example:
   if(anytrue(!isscalar(x,real:T),x <= 0, x != floor(x))){
      error("x is not positive integer")
   }

The apparently more natural way to do the same thing
   if(!isscalar(x,real:T) || x <= 0 || x != floor(x)){
      error("x is not positive integer")
   }
would not do what you want for a non-REAL x since an attempt would be
made to evaluate floor(x), which is illegal for non-REALs.

@@@@see_also#Cross references
See also topics 'logic', alltrue()
@@@@______

====appendnotes()#general,macros,variables
%%%%
appendnotes(x,Notes), Notes a CHARACTER scalar or vector
%%%%
@@@@usage#Usage
appendnotes(x, Notes) appends Notes to the notes "attached" to variable
x.  When x has notes, appendnotes(x, Notes) is equivalent to
attachnotes(x, vector(getnotes(x),Notes)).  When x does not have notes,
appendnotes(x, Notes) is equivalent to attachnotes(x,Notes).

x must be an existing variable of any type, including a structure, a
macro or a GRAPH variable.

Notes must be a CHARACTER scalar or vector, usually containing
descriptive or usage information about variable x.  When Notes is NULL,
any notes attached to x are not changed.

You can retrieve notes using getnotes().  You can test whether a
variable has notes attached using hasnotes().

@@@@see_also#Cross references
See also topics 'notes', attachnotes(), getnotes(), hasnotes().
@@@@______

====arginfo_fun%#general,control
%%%%
Type userfunhelp(user_fun) for information on the structure of user
  functions.
Type userfunhelp(callback_fun) for information on the structure of user
  functions making "call backs" to MacAnova.
Type userfunhelp(arginfo_fun) for information on how to enable automatic
  checking of arguments to a user function.
%%%%
This topic is now in file userfun.hlp.  Type
  userfunhelp(arginfo_fun)

It provides a brief introduction to the form of an arginfo function,
that is, an externally compiled function to be called by MacAnova to
obtain information about the arguments expected by a user function.

Some other useful entries in userfun.hlp are arginfo_fun and
callback_fun.  Type
  userfunhelp()
for a complete list of entries.

====argvalue()#syntax,macros
%%%%
argvalue(var, argName, [, Properties]), var any variable, argName
  CHARACTER scalar, Properties CHARACTER scalar or vector whose elements
  are one or more of "array", "character", "count", "graph", "integer",
  "logic", "macro", "matrix", "nonmissing", "nonnegative", "notnull",
  "number", "positive", "real", "scalar", "square", "string",
  "structure", "TF" and "vector"

%%%%
@@@@usage#Usage
argvalue(Var, argName, Properties), where argName is a quoted string or
CHARACTER scalar and Properties is a CHARACTER scalar or vector, checks
Var to see if satisfies the restrictions specified by Properties.  When
Var does satisfy the restrictions, the value of Var is returned and
argName is ignored.  Otherwise, it is an error and the resulting error
message incorporates argName.

Var can be any defined variable but cannot be a built-in function.

Properties is usually a quoted string or CHARACTER scalar such as
"nonmissing real", made up of one or more words separated by spaces or
tabs.  Alternatively, Properties can be a CHARACTER vector like
vector("nonmissing", "real"), each element of which contains one or more
words.

@@@@properties#Properties
Properties recognized are "array", "character", "count", "graph",
"integer", "logic", "macro", "matrix", "nonmissing", "nonnegative",
"notnull", "number", "positive", "real", "scalar", "square", "string",
"structure", "TF" and "vector".

Not all combinations or words are permitted.  See keyvalue() for
details.

The following properties are abbreviations for combinations of other
properties specifying types of scalars:
  "number" means  "nonmissing real scalar"
  "count"  means  "nonnegative integer scalar"
  "TF"     means  "nonmissing logical scalar"
  "string" means  "character scalar"

Any 3 character or longer initial segment of a property will match it,
except that "nonnegative", "nonmissing", "string" and "structure"
require 4.  For example, "vec", "vect", "vecto", ... all match "vector".
@@@@______

y <- argvalue(var, argName), with no Properties argument, is
essentially equivalent to y <- var except that argName is used in an
error message if var is not defined.

@@@@example#Example
argvalue() is designed to be used in writing macros.  It allows easy
checking of non-keyword macro arguments with automatic printing of
informative error messages.  As a typical example of its use, here is
the text of macro gamma() that uses lgamma() to compute the gamma
function of a REAL array of positive elements:

  if ($v != 1 || $k > 0){error("usage is gamma(x)")}
  @x <- argvalue($1,"$1","positive array")
  exp(lgamma(@x))

Instead of "$1" as argument 2 to argvalue(), you might use "argument 1".
Either choice is likely to yield an informative error message.

When gamma() executed, $1 is replaced by argument 1 to gamma(), $v and
$k are replaced by the number of keyword and non-keyword arguments,
respectively, and $S is replaced by the name of the macro, here 'gamma'.
See topics 'macros', 'macro_syntax' and macro() for details.

  Cmd> gamma(run(4))
  (1)            1            1            2            6

  Cmd> gamma(run(0,2))
  ERROR: run(0,2) is not an array of positive REALs

The second line of the macro was expanded to
  @x <- argvalue(run(0,2),"run(0,2)","positive array")

@@@@see_also#Cross references
See also keyvalue(), nameof(), getkeywords(), isscalar(), isvector(),
ismatrix(), isarray(), isreal(), ischar(), islogic(), ismacro(),
isstruc(), isnumber(), isgraph(), isdefined(), 'macros'.
@@@@______

====arimahelp()#general,time series
%%%%
arimahelp(topic1 [, topic2 ...] [,usage:T] [,scrollback:T])
arimahelp(topic, subtopic:Subtopics), CHARACTER scalar or vector
  Subtopics
arimahelp(topic1:Subtopics1 [,topic2:Subtopics2 ...])
arimahelp(key:Key), CHARACTER scalar Key
arimahelp(index:T [,scrollback:T])
%%%%
@@@@usage#Usage
arimahelp(Topic1 [, Topic2, ...]) prints help on topics Topic1, Topic2,
... related to macros in file arima.mac.  The help is taken from file
arima.mac.

arimahelp(Topic1 [, Topic2, ...] , usage:T) prints usage information
related to these macros.

arimahelp(index:T) or simply arimahelp() prints an index of the topics
available using arimahelp().  Alternatively, help(index:"arima")
does the same thing.

arimahelp(Topic, subtopic:Subtopic), where Subtopic is a CHARACTER
scalar or vector, prints subtopics of topic Topic.  With subtopic:"?", a
list of subtopics is printed.

arimahelp(Topic1:Subtopics1 [,Topic2:Subtopics2], ...), where Suptopics1
and Subtopics2 are CHARACTER scalars or vectors, prints the specified
subtopics.  You can't use any other keywords with this usage.

In all the first 4 of these usages, you can also include help() keyword
phrase 'scrollback:T' as an argument to arimahelp().  In windowed
versions, this directs the output/command window will be automatically
scrolled back to the start of the help output.

arimahelp(key:key) where key is a quoted string or CHARACTER scalar
lists all topics cross referenced under Key.  arimahelp(key:"?") prints
a list of available cross reference keys for topics in the file.
@@@@______

arimahelp() is implemented as a predefined macro.

@@@@see_also#Cross references
See help() for information on direct use of help() to retrieve
information from arima.mac.
@@@@______

====arithmetic#syntax,operations,missing values
%%%%
a + b, a - b, a * b, a / b, a %% b, a^b, -a, +a
a <-+ b, a <-- b, a <-* b, a <-/ b, a <-%% b, a <-^ b
%%%%
@@@@operators#Operators
There are 8 operators for doing arithmetic with MacAnova variables.

     Operators        Precedence  Meaning
       a + b               9      Addition (sum of a and b)
       a - b               9      Subtraction (difference of a and b)
       a * b              10      Multiplication (product of a and b)
       a / b              10      Division (a divided by b)
       a %% b             10      Modular division (see below)
        -a                12      Unary minus ((-1)*a)
        +a                12      Unary plus ((+1)*a))
  a ^ b or a ** b         13      Exponentiation (a to the b-th power)

(Level 11 is the precedence level of matrix multiplication; see
topic 'matrices'.)

@@@@same_sized_operands#Same sized operands
The arithmatic operators are all element-wise operations: When a and b
are vectors, matrices, or arrays with identical dimensions, then c <- a
OP b, computes a result of the same size and shape such that c[i,j,...]
is a[i,j,...] OP b[i,j,...], where OP is one of these operators.
Similarly (-a)[i,j,...]  is -(a[i,j,...]).

  Cmd> vector(1,3,2,0) + vector(8,-1,2,9)
  (1)           9           2           4           9

  Cmd> -vector(1,3,2,0)
  (1)          -1          -3          -2           0

See below for how they work when a and b do not have identical
dimensions.

@@@@modular_division#Modular division
Modular division x %% y computes the non-integral part of x / y or zero
if y exactly divides x.  It is implemented as x %% y = x - y*floor(x/y).
In particular, 17 %% 4 is 1, -17 %% 4 is 3, and -17 %% -4 is -1.  a %% 0
is always MISSING.

@@@@dividing_by_zero#Dividing by zero
When a is not zero, a / 0 yields has value MISSING.  However, 0 / 0 has
value 0.  This can be a useful convention when a and b have the same
pattern of zero elements.

@@@@non_integer_power#Non integer power
When p is not an integer, a^p (or a**p) is defined to be
sign(a)*abs(a)^p and a warning message is printed when a < 0.  0^p is
zero when p > 0 or MISSING when p < 0.  a^0 is always 1, even when a =
0.

@@@@logical_variables#Logical variables
LOGICAL variables and constants may be used in arithmetic expressions
and comparisons.  Values True and False are translated as 1 and 0,
respectively.  In particular 1*w converts a LOGICAL vector, matrix, or
array w to a numerical vector, matrix or array of 0's and 1's..

@@@@missing_values#Missing values
When any elements of a and/or b are MISSING, so is the corresponding
element of a OP b and a warning message is printed.

@@@@too_large_result#Too large result
When any element of the result is too large a number to be represented
in the computer (for example, 1e300/1e-300), the result is set to
MISSING and a warning message printed.

@@@@see_also#Cross references
See subtopic 'options:"warnings"' for information on option 'warnings'
which you can set to suppress warning messages.

@@@@effect_of_precedence_level#Effect of precedence level
The precedence level in the list of operators affects the order of
evaluation when there is more than one operator in an expression.  An
operator with higher precedence is evaluated before one with lower
precedence.  For example, 3 + 2 * 4 is interpreted as 3 + (2*4) = 11
because '*' has higher precedence than '+'.  See topic 'precedence' for
complete information on the order of evaluation.

      Behavior of arithmetic, logical, and bit operations
                 when operands differ in size.

@@@@scalar_operand#Scalar operand
Scalar operand:
  A scalar operand (single number, all dimensions 1) is combined or
  compared with all the elements of the other operand.  For example, x -
  2 subtracts 2 from each element of x and x == 2 compares every element
  with 2.  The result has the same dimensions and labels as the other
  operand.

  When both operands are scalars, the result is unlabeled unless both
  operands have the same number of dimensions and the same labels.  If
  the number of dimensions is different, the result has the larger
  number of dimensions.

@@@@column_vector_op_matrix#Column vector op matrix
Column vector operand and matrix operand:
  When a column vector of length m (m by 1 matrix or vector of length m)
  is combined or compared with a m by n matrix, it is combined or
  compared with each column of the matrix to yield a m by n matrix.  For
  example, when a is 3 by 6, run(3) + a adds 1 to row 1, 2 to row 2, and
  3 to row 3, and a != vector(1,1,2) compares elements in rows 1 and 2
  with 1 and elements in row 3 with 2.

@@@@row_vector_op_matrix#Row vector op matrix
Row vector operand and matrix operand:
  When a 1 by n matrix (a row vector) is combined or compared with a m
  by n matrix, the row vector is combined or compared with each row of
  the matrix.  For example, if x is a matrix

   Cmd> xbar <- sum(x)/nrows(x); resids <- x - xbar

  subtracts the average of the rows of x from every row, since sum(x)
  computes a row vector with the same number of columns as x.  This
  would not work if xbar were computed as xbar <- describe(x,mean:T)
  because describe() computes it as a vector, not a row vector.
  However, in this case, resids <- x - xbar' would work.

@@@@row_vector_op_column_vector#Row vector op column vector
Row vector operand and column vector operand:
  When a column vector of length m is combined or compared with a row
  vector of length n, the result is the m by n matrix obtained by
  combining each element of the column vector with each element of the
  row vector, what might be called an outer product, outer sum, etc.
  Examples
   Cmd> run(2)/run(3)'
   (1,1)           1         0.5     0.33333   [1/1  1/2   1/3]
   (2,1)           2           1     0.66667   [2/1  2/2   2/3]

   Cmd> run(2) <= run(3)'
   (1,1) T       T       T                     [1<=1  1<=2   1<=3]
   (2,1) F       T       T                     [2<=1  2<=2   2<=3]

@@@@structure_operands#Structure operands
Structure operand(s)
  When one of the operands is a structure, each of its components is
  combined with the other argument, following the same rules of
  compatibility just described, producing a structure with the same
  shape as the structure argument.  When both arguments are structures,
  they must have the same number of components at every level and the
  corresponding components are combined.  NULL components are permitted
  as long as they appear in both operands in the same places.
  Example:
   Cmd> structure(x:run(2),y:run(4),z:NULL)/structure(run(3)',4,NULL)
   component: x
   (1,1)           1         0.5     0.33333
   (2,1)           2           1     0.66667
   component: y
   (1)        0.25         0.5        0.75           1
   component: z
   (NULL)

@@@@arithmetic_assignment_operators
                    Arithmetic assignment operators
Operators '<-+', '<--', '<-*', '<-/', '<-^', '<-**', and '<-%%' are
useful for modifying a variable.  They are best illustrated by example.

               a <-+ 3      is equivalent to a <- a + 3
               a <-%% b     is equivalent to a <- a %% b
               a <-^ -1     is equivalent to a <- a^(-1)

To avoid ambiguity, '<-+' and '<--' must be followed by at least one
space so that, for example 'a <-- 3' means 'a <- a - 3' instead of 'a <-
-3'.

You can't modify parts of a vector, matrix or array using assignment
operators.  For example, a[1,2] <-/ 3 is illegal. Use a[1,2] <-
a[1,2]/3.

See topic 'precedence' for information on what happens when more than
one of these operators is used in an expression.

@@@@see_also#Cross references
See also topics 'logic', 'structures', 'syntax', 'bit_ops'.
@@@@______

====array()#variables,combining variables,character variables
%%%%
array(x,n1,n2,...[,KeyPhrases]) or array(x,dimVec [,KeyPhrases]), x
  REAL, LOGICAL or CHARACTER, n1, n2, ... positive integers or dimVec a
  vector of positive integers
KeyPhrases can be labels:structure(lab1,lab2,...), notes:Notes and
  silent:T, where lab1, lab2, ... and Notes are CHARACTER scalars or
  vectors.
%%%%
@@@@usage#Usage
array(x,dimVec) makes an array whose dimensions are the elements of
dimVec, a vector of positive integers.  The data are taken from REAL,
LOGICAL or CHARACTER variable x.  The dimensions of x are ignored, that
is, array(x,dimVec) is equivalent to array(vector(x),dimVec).  For
example, array(run(24),vector(4,3,2)) creates a 4 by 2 by 2 array.

Except when x is a scalar, there must be exactly N elements in x, where
N = product of dimensions.  array() duplicates a scalar N times so, for
example, array(0,2,3,4) is the same as array(rep(0,24),2,3,4).

The data from x are entered with the leftmost dimensions varying fastest
and the rightmost varying slowest.  For example, array(run(20),
vector(5,4)) is equivalent to matrix(run(20),5).

array(x,n1,n2,...) is equivalent to array(x,vector(n1,n2,...)), when n1,
n2, ...  are REAL scalars or vectors.  Most usually n1, n2, ... are
scalars, as in array(run(24),4,3,2) which creates a 4 by 3 by 2 array.

When x is a scalar, vector, matrix or array, array(x), with no
dimensions, is equivalent to array(x,dim(x)), that is, it returns a
variable identical to x, possibly with the addition of coordinate labels
or notes.  See below.

@@@@labels_and_notes_keywords#Keywords 'labels' and 'notes'
You can specify coordinate labels for the output using keyword phrase
'labels:Labels'.  See topic 'labels' for details.

You can attach a CHARACTER vector Notes of descriptive notes to the
result using keyword phrase 'notes:Notes'.  See topic 'notes' for
details.

When no dimensions are specified or the new dimensions exactly match the
dimensions of x, any coordinate labels or descriptive notes of x are
transferred to the result unless 'labels' or 'notes' provide new labels
or notes or are NULL.

@@@@see_also#Cross references
See also topics matrix(), 'matrices', 'subscripts', 'variables'.
@@@@______

====arrays#variables
%%%%
Create an array by                   a <- array(data,dim1,...,dimk)
Extract elements by                  b <- a[j1,...,jk]
Determine the number of dimensions   ndims(a)
Determine the dimensions             dim(a)
Determine the number of elements     length(a)
Reorder subscripts by                b <- a' or b <- t(a,J), permutation
                                     vector J
%%%%
@@@@description#Description
Any REAL, LOGICAL or CHARACTER variable is an array with some number of
dimensions, say M.  To extract or change any single element of an array
you need M subscripts, j_1, j_2, ..., j_M.  See topic 'subscripts'.

The "dimensions" of an array are the maximum permitted values for each
of the M subscripts.  If the dimensions are N_1, N_2, ..., N_M, we
sometimes say the array is N_1 by N_2 by ... by N_M.

When extracting or changing elements of an array using subscripts, it is
an error if any subscript j_k > N_k.

You can create an array A by
  Cmd> A <- array(a,N_1,N_2,...,N_M).
where a is a vector or array with exactly N_1*N_2*...*N_M elements.

A one dimensional array is called a vector and a two dimensional array
is called a matrix.  See topic 'vectors' and 'matrices'.

@@@@order_of_elements#Order of elements
Elements of an array are stored with the first subscript changing most
rapidly, the second changing second most rapidly, and so on, with the
last subscript changing least rapidly.  Thus for a 2 by 2 by 2 array,
the elements are in the order
    a[1,1,1], a[2,1,1], a[1,2,1], a[2,2,1], a[1,1,2], a[2,1,2],
    a[1,2,2],a[2,2,2]

@@@@functions_of_arrays#Functions of arrays
There are several functions that are helpful in working with arrays.  In
the following, A is an array.
  length(A)      The number of elements in A
  ndims(A)       The number of dimensions M of A
  dim(A)         The sizes vector(N1,...,NM) of all the dimensions of A
  a' or t(a)     The same elements of a, with dimensions reversed, so
                 that a'[j1,j2,...,jk] is a[jk,...,j2,j1]
  t(a,J)         The same elements of a with dimensions permuted by
                 elements of vector J so that t(a,J)[K[1],K[2],...,K[k]]
                 is a[K[J[1]],K[J[2]],...,K[J[k]]]
  vector(a)      The elements of a in a vector retaining the order.

max(a), min(a), sum(a) and prod(a) operate along the first dimension of
a, returning an array with the same number of dimensions with the first
dimension 1.

Transformations of an array a such as cos(a) and sqrt(a) return arrays
with the same dimensions as a.

@@@@see_also#Cross references
See also 'variables', 'scalars', 'vectors', 'matrices', length(),
ndims(), dim(), t(), vector(), matrix(), array().
@@@@______

====asciisave()#files,general,output
%%%%
asciisave(FileName [,all:T, v335:T, v406:T, nulls:F, options:F,\
   history:T])
asciisave() repeats previous save() or asciisave() with same options
%%%%
@@@@usage#Usage
asciisave(FileName) saves the MacAnova "workspace", that is, all the
current variables and option values, in a file with name given in the
quoted string or CHARACTER variable FileName.  On versions with windows,
FileName can be "", in which case you will be prompted for the file
name.  The file written is an ASCII coded text file which should be
readable by restore() on any computer on which MacAnova runs.

asciisave(FileName,ascii:F) is equivalent to save(FileName), that is,
the file written will be a binary file instead of an ASCII text file.
This option can be used together with others described below.

asciisave(FileName, var1, var2, .... [,ascii:F]) saves only variables or
macros var1, var2, ... on the file.  When any of the variables saved is
specified in keyword form, the keyword is used for the name.  The items
saved can be restored without deleting everything by
restore(FileName,delete:F).

@@@@file_name_omitted#File name omitted
When FileName is omitted and a previous asciisave() or save() was
executed, the same file will be used as before.  Moreover, when the
previous save() specified an obsolete file format (see save() for
details), the same option will be used, unless explicitly changed.  When
there was no previous save() or asciisave(), omitting the file name is
an error.

@@@@keywords#Keywords
See save() for information on keywords 'all', 'null', 'options',
'graphwind' and 'history' which control whether information on GLM
computations, option values, graph windows and previous commands
should be saved with the workspace.

@@@@difference_from_save#Difference from save()
asciisave() differs from save() in that asciisave() saves the
information in the form of a "text" file that can be transferred between
different types of computers.  Files created by asciisave() are often
bigger than the corresponding file created by save().  On a Macintosh,
the actual type is 'Sasc' rather than 'TEXT'.

The file produced by asciisave() consists of many short lines.  All the
characters written are printable ASCII characters (CR and space through
~), with any other characters in escaped octal format ('\t' for TAB).
The file can be printed, viewed in an editor, or sent by E-mail.  It
cannot be edited safely without specialized knowledge of the actual
format used.

@@@@see_also#Cross references
See also topics restore(), 'files'
@@@@______

====asin()#transformations
%%%%
asin(x [, degrees:T or radians:T or cycles:T]), x REAL or a structure
  with REAL components value in radians (default), cycles, or degrees as
  specified by option "angles" or the optional keyword
%%%%
@@@@usage#Usage
asin(x) computes the inverse sine of the elements of x, where x is a
REAL scalar, vector, matrix or array.  The result has the same shape as
x.  sin(asin(x)) is the same as x except for rounding error.

The units of the result are radians, degrees or cycles as determined by
the value of option 'angles'.  The default is radians.  See subtopic
'options:"angles"'.

asin(x, radians:T), asin(x, degrees:T), asin(x, cycles:T) return results
in the indicated units, regardless of the value of option 'angles'.

When any element of x is MISSING or is above 1 or below -1, the
corresponding element of the result is MISSING and a warning message is
printed.

@@@@structure_argument#Structure argument
When x is a structure, all of whose non-structure components are REAL,
asin(x [,UNITS:T]), where UNITS is one of 'radians', 'degrees' or
'cycles', is a structure of the same shape and with the same component
names as x with each non-structure component transformed by asin().

@@@@examples#Examples
  Cmd> vector(asin(.5),asin(.5,degrees:T),asin(.5,cycles:T))
  (1)      0.5236          30    0.083333

@@@@see_also#Cross references
See topic 'transformations' for information on asin().
@@@@______

====asLong()#transformations,variables
%%%%
asLong(x), x REAL with no MISSING values and with integer values between
  -2147483647 and 2147483647 = 2^31-1.
%%%%
@@@@usage#Usage
asLong(x), where x is REAL returns a LONG variable the same size and
shape as x, but with all of its elements represented as integers instead
of floating point values.  All the elements of REAL scalar, vector,
matrix or array x must be exact integers with values between -2147483647
and 2147483647 = 2^31-1.

The only use at present for asLong() is to create a long integer
argument to a user function called by User().  When the argument is
returned it is "coerced" to an equivalent REAL variable.  For example,
User("foo", result:asLong(20)) will return a REAL integer scalar value.

asLong(x) is also legal as an argument to print() and write().  For
example, print(asLong(vector(1,3,5,2))) produces the same output as
print(vector(1,3,5,2)).

When assigned (y <- asLong(x)), a LONG variable is "coerced" to a
ordinary REAL variable.  For example, a <- asLong(vector(1,3,5,2))
has the same effect as a <- vector(1,3,5,2).

@@@@see_also#Cross references
See also topics 'variables' and, in file userfun.hlp, User() (type
userfunhelp(User).
@@@@______

====assignment#syntax
%%%%
a <- x assigns value of x to a.
a[J1] <- x, a[J1,J2] <- x, ..., where the J's are valid subscripts,
  replaces the designated elements to corresponding elements of x.
a[J] <- x, when a is a structure, replaces the designated components
  of a by x, J a valid subscript
a <-+ x assigns a + x to a and similarly for a <-- x, a <-* x, a <-/ x,
  a <-%% x and a <-^ x.
When Str is a structure"
  Str$a <- x, Str$a$b <- x, ..., Str[[i]] <- x, Str[[i]][[j]] <- x, ...
  replaces the indicated component of Str by x
%%%%
@@@@introduction#Introduction
This topic describes the use of the assignment operator '<-' and
arithmetic assignment operators '<-+', '<--', '<-*', '<-/' and '<-%%'.
It has sections on ordinary assignment, assignment to subscripts,
assignment to structure components and arithmetic assignment operators.

@@@@ordinary_assignment
                          Ordinary assignment
You can assign values to a variable using the left pointing arrow '<-'
made up of the two characters "less than" and "minus".  For example,
'foo <- 5' assigns the value 5 to the variable foo.  When foo does not
already exist, it is created; otherwise, its previous value is discarded
and foo is re-defined.

An expression of the form 'y <-3', say, is always interpreted as 'y <-
3' rather than as 'y < -3'.  When you want the latter, be sure to put a
space before '-3'.

The value of such an assignment is the value of the variable after the
assignment.  For example, 'y <- exp(x <- 4)' sets variables x and y to 4
and exp(4), respectively, and 'y <- x <- 4' assigns 4 to both x and y.

This value is normally not printed unless the assignment is the last
command in a compound command {command_1;...;command_k}.

For example, '{y <- 3}' not only assigns the value 3 to y put also
prints the number 3, although 'y <- 3' by itself prints nothing.  For
this reason, it is a often a good idea to terminate compound commands
with ';;', as in '{y <- 3;;}'.  Of course, this is a bad idea if you
want the final value to be printed or if you are assigning the value of
the entire compound statement to a variable.

Some "special" variables such as CLIPBOARD can be assigned to.  What
actually happens depends on the particular variable.  You cannot assign
to special structure variable GRAPHWINDOWS although you can assign to
its components.  See topics 'CLIPBOARD', 'GRAPHWINDOWS' and
'graph_assign'.

@@@@assignment_to_subscripts
                        Assignment to subscripts
You can modify parts of an existing vector, matrix or array y by
y[J1] <- x, y[J1,J2] <- x, y[J1,J2,J3] <- x, ... as long as the
subscripts are appropriate.  You can use positive, negative and LOGICAL
vector subscripts or a single matrix subscript, but not an array
subscript with more than two dimensions.

x must be the same type variable as y, REAL, CHARACTER or LOGICAL.  When
x is a scalar (number, T or F or quoted string), it replaces all the
elements of y selected by the subscripts.  When x is not a scalar, then
length(x) must match the number of elements of y selected, but x can be
of any shape and is treated as if it were vector(x).

The value of an assignment to subscripts is a vector, matrix or array
containing the new elements and having the same shape as the elements of
y that were replaced.

It is legal for the subscripts to select the same element of x more than
once (for instance, y[vector(1,1,2)] <- vector(3,5,7)).  In this case
the eventual value for an element selected more than once is the last
element in x assigned to that element (in the example, y[1] is set to
5).

See below for using subscripts to change components of an existing
structure.

@@@@NULL_or_non_selecting_subscripts#NULL or non-selecting subscripts
y[J1] <- NULL, y[J1,J2] <- NULL, ... are legal provided at least one of
the subscripts is NULL or is non-selecting (is all False or is a
complete set of negative subscripts).  y is not changed and the value of
the assignment is NULL.  For example, even if all the elements of u are
positive, y[u < 0] <- x[u < 0] is legal and does not change y.

Similarly, when x is a scalar of the appropriate type , y[J1] <- x,
y[J1,J2] <- x, ... is legal even one or more subscripts are NULL or
non-selecting. y is not changed and the value of the assignment is NULL.
For example, y[vector(y) > 10] <- 10 is legal even when there are no
elements of y greater than 10.

It is an error to assign a non-NULL non-scalar variable to subscripts
when there is a NULL or non-selecting subscript.

@@@@vector_subscript_for_matrix_or_array#Vector subscript for matrix or array
Suppose y is a matrix or array and J is a vector such that vector(y)[J]
is legal, and x is a scalar or a vector with the same length as
vector(y)[J].  Then y[J] <- x is legal and assigns the elements of x to
the positions that would be specified by J if y were a vector.  The
dimensions of y are retained.  For example,
  Cmd> y[vector(abs(y)) > 3] <- ?
replaces all elements of y that exceed 3 in absolute value by MISSING,
without disturbing the dimensioning of y.

Similarly, when x is a scalar or is a vector, matrix or array with
length(x) = length(y), y[] <- x replaces all the values of y by values
from x without changing the dimensions of y.

When y is not a structure, y[[J]] <- x is illegal except when J = 1 in
which case it is equivalent to y <- x.

See below (assignment:"assignment_to_structure_components") for
assignment to components of a structure.

@@@@examples#Examples
Examples assuming x is a vector of length 5 and y is a 3 by 2 matrix.

  Cmd> y <- x[-run(2)] <- 17
sets all the elements of except x[1] and x[2] to 17 and sets y to
vector(17,17,17).

  Cmd> y <- x[vector(1,4)] <- vector(17,19)
sets x[1] and x[4] to 17 and 19 and y to vector(17,19)

  Cmd> y <- x[vector(1,3,1)] <- vector(17,19,21)
sets x[1] and x[3] to 21 and 19 and y to vector(17,19,21).

  Cmd> y[vector(1,4)] <- run(3)
is illegal because there are 3 elements in run(3), but only 2 elements
are selected in y.

  Cmd> y <- x[-1,] <- run(4) # change all but row 1 of x
changes x[2,1], x[3,1], x[2,2] and x[3,2] to 1, 2, 3 and 4,
respectively, and sets y to the 2 by 2 matrix matrix(run(4),2).

  Cmd> y <- x[hconcat(run(2),run(2))] <- 4 #matrix subscript
sets x[1,1] and x[2,2] to 4 and y to vector(4,4).

  Cmd> y <- x[x>max(x)] <- 3
doesn't change x and sets y to NULL because x > max(x) has value
vector(F,F,F,F,F).

@@@@assignment_to_structure_components
                   Assignment to structure components
You can assign to structure components by name or by number.  In the
following Str is assumed to be an existing structure variable, not the
result of an operation like describe(x).

When a component of Str has name Name, Str$Name <- x replaces that
component by the value of x without changing it's name.  The value of
the assignment expression is x.  If more than one component is named
Name, assignment is to the first such component.  It is an error if Str
has no such component.

Str$Name1$Name2 <- x, Str$Name1$Name2$Name3 <- x, ... are also legal,
provided the indicated component exists.

Str[J] <- x and Str[[J]] <- x are identical and work similarly to a[J]
<- x, when a is a vector, matrix or array, except that entire components
are replaced.  The names of components in Str are never changed.

There are four cases depending on x and K = number of components
selected in Str by J, counting any duplicated subscripts more than once.

1.  When K = 1, the selected component is always replaced by a copy of
x, whether x is a structure or a non-structure.

2.  When K > 1 and x is a structure with ncomps(x) = K, the selected
components in Str are replaced by copies of the corresponding components
of x and the value is identical to x.  When a component of Str is
selected more than once, its new value is the highest numbered component
of the x that was assigned to it.  The value of the assignment is a copy
of x.

3.  When K > 1 and x is not a structure or is a structure with ncomps(x)
!= K, each selected component of Str is replaced by a copy of x.  The
value is structure(x,x,...,x), where there are K copies of x.

4.  When K = 0, that is, no component of Str is selected as in
Str[rep(F,3)], x is ignored, Str is not changed and the value is NULL.

In addition, you can specify by number components of components to be
changed.  For example, Str[[3]][[2]] <- x replaces component 2 of the
third compoent of Str by x and Str[[3]][[-1]] <- x replaces all but the
first component of the third component of Str by x.  If x is a structure
with the right number of components, each component of Str[[3]][[-1]] is
replaced by the correspoding component of x.  Otherwise, each component
of Str[[3]][[-1]] is replaced by x.

You can nest component specificiation, mixing names and [[...]]
subscripts up to 31 deep.  All subscripts except possibly the final one
must be integer scalars.  With nested components, no [...] subscripts
are allowed, that is, Str[[1]][3] <- x is illegal; use Str[[1]][[3]] <-
x.

@@@@arithmetic_assignment_operators
                    Arithmetic assignment operators
There are several arithmetic assignment operators: <-+, <--, <-*, <-/,
<-%% and <-^.  For example, a <-* b is equivalent to a <- a*b and a <-^
b is equivalent to a <- a^b.  '<--' and '<-+' require a following space.

The variable being modified cannot be subscripted or be a structure
component.  For example, x[3] <-+ 1 and Str$x <-- 1 are illegal.  See
topic 'arithmetic' for more information.
@@@@______

====atan()#transformations
%%%%
atan(x [, degrees:T or radians:T or cycles:T]), x REAL or a
  structure with REAL components; value in radians (default), cycles, or
  degrees as specified by option 'angles' or the optional keyword
atan(x,y [, degrees:T or radians:T or cycles:T]), y REAL or a structure
  with real components the same size and shape as x
%%%%
@@@@usage#Usage
atan(x) transforms the elements of REAL vector, matrix, or array x to
inverse tangents (arctangents).  When x is a structure with components
x1,...,xm, atan(x) is a structure with components atan(x1),...,atan(xm).

When any element of x is MISSING, the corresponding element of atan(x)
is MISSING.

atan(x,y) computes theta = arctan(x/y), with the result in the
appropriate quadrant, where x and y must be REAL vectors, matrices, or
arrays with the same dimensions.  Specifically, theta is chosen so that
sin(theta) has the same sign as x, cos(theta) has the same sign as y and
tan(theta) = x/y.

atan(x,y) is also defined when x and y are both structures with the same
number of components, say x is structure(x1,...,xm) and y is
structure(y1,..., ym) .  The result is what would be produced by
structure(atan(x1,y1),...,atan(xm,ym)).

@@@@units#Units
The units of the result of atan(x) and atan(x,y) are radians, degrees or
cycles as determined by the value of option 'angles'.  The default is
radians.  See subtopic 'options:"angles"'.
@@@@______

@@@@keywords#Keywords
atan(x, radians:T), atan(x, degrees:T), atan(x, cycles:T), atan(x, y,
radians:T), atan(x, y, degrees:T) and atan(x, y, cycles:T) return values
in the specified units, overriding option 'angles'.

@@@@see_also#Cross references
See topic 'transformations' for more information about atan(), including
its use with a CHARACTER argument.

See also topics 'structures', 'labels'.
@@@@______

====atanh()#transformations
%%%%
atanh(x), x REAL or a structure with REAL components
%%%%
@@@@usage#Usage
atanh(x) returns the inverse hyperbolic tangent of the elements of x,
when x is a REAL scalar, vector, matrix or array.  The result has the
same shape as x.  In terms of other functions, atanh(x) =
.5*log((1+x)/(1-x)).

This transform is sometimes called the Fisher z-transform.  When r is a
sample Pearson correlation from a bivariate normal sample of size N and
population correlation rho, atanh(r) is approximately normal with mean
rho and variance 1/(N-2).

When any element of x is MISSING, so is the corresponding element of
atanh(x).  When any element of x >= 1 or <= -1, the corresponding
element of atanh(x) is MISSING.  In both cases a warning message is
printed.

@@@@structure_argument#Structure argument
When x is a structure, all of whose non-structure components are REAL,
atanh(x) is a structure of the same shape and with the same component
names as x, with each non-structure component transformed by atanh().

@@@@see_also#Cross references
See topic 'transformations' for more information on atanh().
@@@@______

====attachnotes()#general,macros,variables
%%%%
attachnotes(x,Notes), Notes a CHARACTER scalar or vector or NULL
%%%%
@@@@usage#Usage
attachnotes(x, Notes) "attaches" Notes to variable x as descriptive
"notes".

When Notes is NULL, any existing notes are removed from x.  Otherwise,
Notes must be a CHARACTER scalar or vector, usually containing
descriptive information about variable or macro x.

x must be an existing variable of any type, including a structure, a
macro or a GRAPH variable.  You can't attach notes to certain special
variables like CLIPBOARD and GRAPHWINDOWS.

You can retrieve notes using getnotes() and append notes to previously
attached notes using appendnotes().  You can test whether a variable has
notes attached using hasnotes().

@@@@see_also#Cross references
See also topics 'notes', appendnotes(), getnotes(), hasnotes().
@@@@______

====autoreg()#time series
%%%%
autoreg(Phi,A [,reverse:T, limits:vector(i1 [,i2]), start:startVals,\
  seasonal:L]), REAL vector or NULL Phi, REAL vector or matrix A, REAL
  startVals the same size and shape as A, positive integer L
%%%%
@@@@introduction#Introduction
autoreg() is designed to implement an autoregressive operator as the
term is used in ARIMA time series analysis.  It can also be used to
compute partial sums of a series or, together with movavg(), to find the
power series coefficients of rational functions.

@@@@usage#Usage
autoreg(Phi,A) applies the autoregressive operators specified by the
columns of the REAL matrix Phi to the columns of the REAL matrix A.
When ncols(Phi) = 1, Phi is applied to every column of A and if ncols(A)
= 1, each column of Phi is applied to A.  The result is a matrix with
nrows(A) rows and max(ncols(Phi), ncols(A)) columns.  When both Phi and
A have more than one column, they must both have the same number of
columns.

Specifically, assuming for simplicity that both Phi and A are vectors so
that the result x is a vector,
    x[i] = A[i] + sum(Phi[k]*x[i-k],1<=k<=nrows(Phi)),
with x[l] taken to be 0 for l < 1.

When Phi is a vector, movavg(Phi,A) can be expressed in matrix terms as
solve(Phi1, A), where Phi1 is a nrows(A) by nrows(A) matrix.  For
example, when nrows(Phi) = 2,
         [   1        0        0       0   ...    0        0       0 ]
         [-Phi[1]     1        0       0   ...    0        0       0 ]
  Phi1 = [-Phi[2]  -Phi[1]     1       0   ...    0        0       0 ]
         [   0     -Phi[2]  -Phi[1]    1   ...    0        0       0 ]
         [ ......................................................... ]
         [   0        0        0       0   ... -Phi[2]  -Phi[1]    1 ]
See also solve().

NOTE: The sign assumed for Phi is not affected by variable ARSIGN which
is recognized by several macros in file Arima.mac.  Type
arimahelp(MASIGN) for details.

When Phi is NULL, the result is the same as A, stripped of labels or
notes, if any.  Also, the result is a true vector or matrix (ndims = 1
or 2).

@@@@inverse_difference_operator#Inverse difference operator
A common usage is autoreg(1,x), where x is a vector or matrix.  This
computes the partial sums x[1,], x[1,]+x[2,], ..., sum(x).  A useful
macro might be defined by
    partialsum <- matrix("autoreg(1,$1)")

@@@@keyword_reverse#Keyword reverse
autoreg(Phi,A,reverse:T) applies the autoregressive operator in reverse:
    x[i] = A[i] + sum(Phi[k]*x[i+k],1<=k<=nrows(Phi)),
with x[l] = 0 for l > nrows(A).

@@@@keyword_seasonal#Keyword seasonal
autoreg(Phi,A,seasonal:L [,reverse:T) does the same, except that the
computations are of the forms
    x[i] = A[i] + sum(Phi[k]*x[i-k*L],1<=k<=nrows(Phi)).
or
    x[i] = A[i] + sum(Phi[k]*x[i+k*L],1<=k<=nrows(Phi)) (reverse:T)

@@@@start_and_limits#Start and limits
autoreg(Phi,A,limits:vector(i1,i2),start:StartVals [,reverse:T,
seasonal:L]) is the same except that x[i] is computed as described only
for i1 <= i <= i2, with the remaining values copied before the
computation from rows 1 to i1-1 and rows i2+1 to nrows(A) of matrix
StartVals.  The values in rows 1 through i1-1 of StartVals serve as
"starting values" for the autoregressive operator.  When reverse:T is an
argument, rows nrows(A) through i2+1 serve as starting values.  This
feature is useful for generating out of sample forecasts or "backcasts".

The value for limits can also be a scalar j between 1 and nrows(A).  In
this case, with reverse:T, i1 = 1, i2 = j, and without reverse:T, i1 =
j, i2 = nrows(A).

StartVals must have the same number of columns as A and usually has the
same number of rows.  When nrows(StartVCals) != nrows(A), without
reverse:T, i2 must be nrows(A) and with reverse:T, i1 must be 1.  In
this case, the elements of StartVals, which are used as starting values,
are copied to the rows not included between i1 and i2 and hence
nrows(start) must match nrows(A) - (i2 - i1 + 1).  This feature allows
you to compute autoregressive predictions up to 20 time units ahead,
say, by
  Cmd> autoreg(phi,rep(0,length(x) + 20),limits:length(x)+1,start:x)

autoreg() is the inverse of movavg() and vice versa, in that
   autoreg(phi,movavg(phi,x))  and   movavg(phi,autoreg(phi,x))
both reproduce x, except for rounding error.

@@@@examples#Examples
Examples:
  Cmd> autoreg(phi,rnorm(400))[-run(100)]
    generates an autoregressive series with normal innovations,
    discarding the first 100 values to avoid transients.
  Cmd> autoreg(phi,matrix(rnorm(4000),400)[-run(100),]
    generates 10 independent autoregressive series at once.
  Cmd> autoreg(hconcat(phi1,phi2),rnorm(400))[-run(100)]
    generates 2 autoregressive series with different coefficients but
    the same innovations
  Cmd> autoreg(.3, autoreg(-.1,rnorm(230),seasonal:4))[-run(30)]
     generates a (1,0,0)x(1,0,0)-4 seasonal ARMA time series
  Cmd> autoreg(vector(1,1),padto(1,20))
     computes the first 20 Fibonacci numbers F(j) satisfying F(j) =
     F(j-1) + F(j-2) with F(1) = 1, F(0) = 0

@@@@see_also#Cross references
See also movavg().
@@@@______

====batch()#syntax,control,files
%%%%
batch(fileName [,echo:T or F, prompt:string]), CHARACTER scalars
  fileName and string
%%%%
@@@@usage#Usage
batch(FileName) executes the commands in the file with name given in the
quoted string or CHARACTER variable FileName.  It must be the last
command in a line or a compound command surrounded by '{' and '}' and
must not be in a loop.

In windowed version, if FileName is "" you will be prompted to enter
the file name in a dialog box.

Lines of the file are read sequentially and executed as if they were
typed at the keyboard.  Normally, each line is printed with the file
name as prompt before it is executed.  You can suppress this by using
keyword phrase echo:F (see below), or by previously executing
setoptions(batchecho:F) (see topics setoptions() and 'options').

The batch file can contain any sequence of MacAnova commands.  This
includes additional batch() commands that do not read from a batch file
currently in use.

@@@@example#Example
Here is an example of a short batch file designed to do cubic regression
of variable y on variable x and do a plot of residuals against x (see
also regress() and plot()):

   xsq <- x * x
   xcub <- x * xsq
   regress("y=x + xsq + xcub")
   plot(x, RESIDUALS, title:"Cubic regression residuals vs x")

@@@@treatment_of_errors#Treatment of errors
When an error occurs, the default behavior is to terminate all current
batch() commands.  You can use setoptions(errors:N), where N is a
positive integer to increase the number of errors tolerated before
termination.  See topic 'options"errors"' for details.

@@@@keywords#Keywords
batch(FileName,echo:F) works the same as batch(FileName) except the
prompts and lines read from the file are not printed.  This status is
inherited by batch files invoked from within a batch file.  You can use
setoptions(batchecho:F) to set the default behavior of batch() so that
lines will not be echoed.

batch(FileName,echo:T) forces the printing of prompts and commands, even
if option 'batchecho' has been set False (see subtopic
'options:"batchecho').

NOTE: If you want to suppress printing of both prompts and output, put
  setoptions(quiet:T)
at the start of the file and
  setoptions(quiet:F)
at the end of the file.  See subtopic 'options:"quiet"'.

batch(FileName,prompt:Prompt), where Prompt is a quoted string or
CHARACTER scalar, forces echoing, with command lines starting with
Prompt instead of the file name.  When the batch file contains a
setoptions(prompt:newPrompt) command, newPrompt overrides Prompt.  A
subsequent setoptions(default:T) in the file, restores Prompt.  See
topics setoptions(), 'options'.
@@@@______

@@@@see_also#Cross references
See also topic 'launching'.
@@@@______

====bcprd()#matrix algebra,glm
%%%%
bcprd(x), REAL matrix x
bcprd(x1, x2, ... ), x1, x2, ... REAL matrices with the same number of
  rows.
%%%%
@@@@usage#Usage
bcprd(x) where x is a matrix computes a "bordered" cross product matrix
containing the means of the columns of x and mean-corrected sums of
squares and products of the columns of x.

bcprd(x1,x2,...,xm) yields the same result as bcprd(hconcat(x1,x2,...,
xm)) when x1, x2, ... are all REAL matrices with the same number of
rows.

Specifically, when x is an n by p matrix, bcp <- bcprd(x) sets bcp to
a p+1 by p+1 matrix, where
  bcp[1,1]   = 1/n
  bcp[-1,1]  = a column vector containing the sample mean xbar
  bcp[1,-1]  = a row vector containing -xbar'
  bcp[-1,-1] = the p by p matrix of mean-corrected sums of squares and
               products of the columns of x

@@@@relationship_with_swp#Relationship with swp()
bcprd(x) is mathematically equivalent to
  {@TMP <- hconcat(rep(1,nrows(x)),x); swp(@TMP %c% @TMP,1)}.
However, the use of bcrpd() is preferred to the illustrated use of swp()
since it uses a numerically stable algorithm to compute the corrected
sums of squares and products.

@@@@labels#Labels
When all the arguments of bcprd() have labels, so will the result of
bcprd() with both row and column labels taken from the column labels of
the arguments.

@@@@see_also#Cross references
See also swp().
@@@@______

====bin()#categorical data,summary statistics
%%%%
bin(x,Bnds [,silent:T,leftendin:T]), x a REAL matrix, Bnds REAL vector,
   Bnds[k] < Bnds[k+1]
bin(x,vector(anchor,width) [,leftendin:T]), anchor and width > 0 REAL
   scalars
bin(x,nbins, [leftendin:T]), nbins positive integer.
bin(x [,leftendin:T])
%%%%
@@@@usage#Usage
bin(x,Edges) counts the number of values v in each column of REAL vector
or matrix x in class intervals defined by the elements of REAL vector
Edges with length(Edges) > 2.  Edges must satisfy Edges[k] < Edges[k+1],
k = 1, ..., nclasses = length(Edges) - 1.  When x is a matrix, counts
are computed for each column of x.

The value of bin(x,Edges) is structure(boundaries:edges, counts:M) where
edges is a vector of length nclasses + 1 containing the class limits and
M contains counts.  In this usage, edges is identical to Edges.  When x
is a vector, M[k] = (number of values of x in class k).  When x is a
matrix, M is a matrix with nclasses rows and ncols(x) columns with
M[k,j] = (number of values in column j of x in class k).

The count for class k is the number of values v with Edges[k] < v <=
Edges[k+1], k = 1, ..., nclasses, that is any value equal to the right
end of an interval is counted in that interval.

When any element of x is <= Edges[1] or > Edges[nbins+1], it is not
included in the count and a warning message is printed.

@@@@leftendin_keyword#Keyword 'leftendin'
bin(x,Edges,leftendin:T) does the same except a value v is counted in
class k if Edges[k] <= v < Edges[k+1], that is, a value equal to the
left end of a class is counted as being in the class.  v is not counted
when v < Edges[1] or v >= Edges[nbins+1].  'leftendin:T' can be used
with all variants of bin() arguments

@@@@silent_keyword#Keyword 'silent'
bin(x,Edges,silent:T) does the same except any warning messages are
suppressed.  'silent:T' can be used with all variants of bin()
arguments.

@@@@equal_width_classes#Equal width classes
bin(x,vector(anchor, width)), where anchor and width are scalars, does
the same, except that the class boundaries are of the form anchor +
k*width, where k is an integer, with the minimum and maximum values of k
selected so as to include all the data in x.  For example, bin(x,
vector(.5,1)) would use class intervals of width 1 centered at integers.

bin(x,nbins) does the same, except that boundaries for nbins classes are
computed so that the classes have equal widths and include all the data.
The class boundaries will normally not be "neat".

bin(x) is equivalent to bin(x, ceiling(log(nrows(x))/log(2))+1), that is
the number of bins is approximately log2(nrows(x)).

You can use bin() to find counts needed to draw a histogram or to
compute a chi-squared test of goodness of fit of a sample to a
theoretical distribution.

====bit_ops#operations,glm,missing values
%%%%
a %| b, a %^ b, a %& b and %! a, where a and b are REAL or structures
  with REAL components with integer elements >= 0 and <= 4294967295 =
  2^32-1 nbits(x)
%%%%
There are 4 operators for working with integers considered as the sets
of 32 bits specified by their binary representations.

@@@@bit_operations#Bit operations
Bit Operation  Precedence  Meaning
    a %| b         1       Bitwise Or (OR)
    a %^ b         2       Bitwise Exclusive Or (XOR)
    a %& b         3       Bitwise And (AND)
      %!a          4       Bitwise Complement (COMPL)

When an operand x is not an integer or x < 0 or x > 4294967295 = 2^32-1,
the result of any of these operators is MISSING.
@@@@______

For '%&', a bit of the result is 1 if and only if the corresponding bits
in the operands are both 1.
  Example: 25 %& 19 is 17 because 11001b AND 10011b is 10001b

For '%|', a bit of the result is 1 if and only if at least 1 of the
corresponding bits in the operands is 1.
  Example: 25 %| 19 is 27  because 11001b OR 10011b is 11011b

For '%^', a bit of the result is 1 if and only if exactly 1 of the
corresponding bits in the operands are 1, that is, if the corresponding
bits differ.
  Example: 25 %^ 19 is 10  because 11001b XOR 10011b is 01010b

Operator '%!' operates on the immediately following variable considered
as a collection of 32 bits, changing 1's to 0's and 0's to 1's.
  Examples:
       %! 25 is 4294967270 since COMPL(0000000000000000000000000011001b)
          is 11111111111111111111111111100110b
       %! 0  is 4294967295 since COMPL(0000000000000000000000000000000b)
          is 11111111111111111111111111111111b

When an operand is LOGICAL, it is treated as having value 0 (F) or 1
(T).  The result is always REAL.

When any operand is MISSING, so is the result.

@@@@use_with_modelinfo#Use with modelinfo()
Bit operators were introduced to be useful with the output of
modelinfo(bitmodel:T).  For example, 2^(i-1) %& modelinfo(bitmodel:T)[j]
is non-zero if and only if the j-th term of the model contains the i-th
factor or variate (assuming i <= 32).
@@@@______

The operators were listed above in increasing order of precedence.
Moreover, they have lower precedence that all arithmetic, comparison, or
logical operators which means they are evaluated after all such
operators.

@@@@examples#Examples
  Examples:
    Expression                 Interpretation              Value
    17 %| 29 %^ 91 %& 11       17 %| (29 %^ (91 %& 11))    23
    %!21 %| 97 %& %! 33        (%!21) %| (97 %& (%!33))    4294967274
    1 %& 3 + 4                 1 %& (3+4)                  1
    3 %^ 5 != 6                3 %^ (5 != 6)               2
    1 %| 2 == 3                1 %| (2 == 3)               1
    %!0 == 4294967295          %!(0 == 4294967295)         4294967295

To understand the last three examples, note that 5 != 6 is True and is
interpreted as 1, and that 2 == 3 and 0 == 4294967295 are both False and
are interpreted as 0. See topics 'arithmetic' and 'logic'.

@@@@see_also#Cross references
See topic 'arithmetic' for a description of the "shape" of the result
when operands are not scalars.

See also modelinfo(), nbits().
@@@@______

====boxcox()#transformations
%%%%
boxcox(x,power), x a REAL vector or matrix, power a REAL scalar
%%%%
@@@@usage#Usage
boxcox(var,Pow) computes the Box-Cox transformation of the data in
vector or matrix var.  When var is a matrix, the transformation is
applied to each column separately.  If GM is the geometric mean of the
values in a vector, boxcox(y,Pow) computes (y^Pow-1)/(Pow*(GM)^(Pow-1))
when Pow != 0, and GM*log(y) when Pow == 0.  Boxcox is implemented as a
macro.

@@@@see_also#Cross references
See also topics 'macros' and 'transformations'.
@@@@______

====boxplot()#plotting,descriptive statistics
%%%%
boxplot(x1,x2,...,xk [,vs:indv, boxsize:W] [,vertical:T, excludeM:T,
  boxtype:m, symbols:outlierSyms, graphics keyword phrases]), x1,...,xk
  REAL vectors, indv REAL length k vector with no MISSING values, m > 0
  integer, W REAL non-negative vector or scalar, outlierSyms CHARACTER
  scalar or vector of length 2
boxplot(Struc, [,vs:indv, boxsize:W] [,vertical:T, excludeM:T,
  boxtype:m, symbols:outlierSyms, graphics keyword phrases]), Struc a
  structure with k REAL vector components
%%%%
@@@@usage#Usage
boxplot(x1, x2, ... , xk) produces horizontal parallel Tukey boxplots
for the vectors x1 through xk and plotting positions 1, 2, ..., k on the
y axis.

boxplot(x1, x2, ... , xk,vertical:T) and boxplot(Struc,vertical:T) do
the same except the boxplots are aligned vertically at plotting
positions 1, 2, ..., k on the x axis.  Pre-defined macro vboxplot()
which is used identically to boxplot(), makes use of the feature to make
vertical boxplots.

boxplot(x1, x2, ..., xk, vs:Predictor [,vertical:T] ...) does the same
except the boxes are aligned with Predictor[1], Predictor[2], ...,
Predictor[k] on the y or x axis.  Predictor must be a REAL vector with
no MISSING values with length(Predictor) = k.

boxplot(x1, x2, ..., xk, boxsize:W, ...) does the same except the
thickness of the boxes is determined by non-negative REAL scalar or
vector W.  See below for details.

boxplot(x1, x2, ..., xk, boxtype:m, ...) does the same except the style
of the boxplot is determined by integer m > 0.  The default type
corresponds to m = 1.  Whiskers extend to the most extreme values inside
the inner "fences", and values beyond the inner and outer fences are
individually plotted with special symbols.

With boxtype:2, the box plot is a 5 number summary box plot, with
whiskers with cross bars at the end extending from the ends of the box
to the extremes.  No outliers are indicated.  At present, boxtype:m with
m > 2 yields as boxtype:1.

boxplot(Struc, ....) produces parallel box plots for the components of
structure Struc, all of which must be REAL vectors.  You can use any
boxplot() or graphical keywords.

@@@@symbols_keyword#Keyword 'symbols'
Keyword 'symbols' has a different meaning from other plotting commands.
You use it to specify symbols for moderate outliers (beyond inner fences
and inside outer fences) and extreme outliers (beyond outer fences).
The value of 'symbols' must be a CHARACTER scalar or vector of length 2.

  Cmd> boxplot(x1, x2, x3, symbols:vector("\3", "\5"))

uses "\3" (square) as a symbol for moderate outliers and "\5" (triangle)
as a symbol for extreme outliers.  When the value of 'symbols' is a
scalar, the default symbol is used for extreme outliers.

@@@@use_with_split#Use with split()
boxplot(split(y,a) [,vertical:T] ... ) draws parallel box plots of the
data in vector y classified according to levels of factor a.  See
split().

boxplot(split(y) [,vertical:T], ...) draws parallel box plots of the
data in each column of matrix y.

These work because split() returns a structure and each component of a
structure gets its own box.

@@@@size_of_boxes#Size of boxes
You can use keyword phrase boxsize:W, where W is a non-negative scalar
or vector to specify the "thickness" of the boxes (height for horizontal
boxes, width for vertical boxes).  When W is not a scalar, length(W)
must match the number of boxes.  When W is a vector and W[j] = 0, box j
is omitted.

When you don't use keyword 'boxsize', the default thickness is such that
about 2/3 of the space between the first and last box is made of up
boxes and 1/3 of interbox space.

@@@@keywords#Keywords
When keyword phrase 'excludeM:T' is an argument, and the number of
non-MISSING values in a sample is odd, the median is omitted in
calculating the quartiles as the medians of the upper and lower halves.

You may use keywords 'dumb', 'xmin', 'xmax', 'ymin', 'ymax', 'logx',
'logy', 'xlab', 'ylab', 'title', 'xaxis', 'yaxis', 'borders', 'ticks',
'xticks', 'yticks', 'xticklen', 'yticklen', 'xticklabs', 'yticklabs',
'height', 'width', 'pause', 'silent' and 'notes' as for other plotting
commands.  See topics 'graph_keys', 'graph_border' and 'graph_ticks'

When option 'dumbplot' has been set False (see subtopic
'options:"dumbplot"'), the plot will be a low resolution plot unless
'dumb:F' is an argument.

Note: Using 'logx:T' and/or 'logy:T' affects only the scaling used in
plotting, not the determination of outliers.  With logy:T without
vertical:T or logx:T with vertical:T`q, the thickness of the boxes will
be affected since the edges are equally distant from the middle in
arithmetic units but not in logarithmic units

@@@@see_also#Cross references
See topic 'graph_files' for information on how to save a boxplot in a
file using keywords 'file', 'new, 'ps', 'screendump', and 'epsf'.

See also topics showplot(), 'structures', 'graph_keys'.
@@@@______

====break#control,syntax
%%%%
for(i,run(n)){if(x[i] < 0){break} .... }
for(i,run(n)){for(j,run(m)){if(x[i,j] < 0){break 2} .... }}
%%%%
@@@@usage#Usage
'break' and 'break n' are used to exit prematurely from one or more
enclosing loop, perhaps because an error has been found.

'break', in a 'for' or 'while' loop, exits the loop, skipping any
remaining commands in the loop and resuming execution immediately after
the '}' terminating the loop.  When more than one loop "encloses"
'break', only the innermost one is exited.

'break n', where n is a positive integer, exits from n enclosing 'for'
or 'while' loops.  For example, 'break 1' is equivalent to 'break' and
will exit the current loop; 'break 2' will exit the current loop and the
loop enclosing it; and so on.  n must be a literal integer ('1', '2',
...)  and not a variable with integer value.

It is an error to use 'break' outside of a loop or to use 'break n' when
not enclosed in at least n loops.

@@@@in_macro_or_evaluated_string#In macro or evaluated string
In an evaluated string or out-of-line macro, 'break' and 'break n' can
be used only to exit from a loop that started in the macro or evaluated
string.  It is an error to try to exit from a loop that started outside
the macro or evaluated string.  See evaluate() and 'macros'.

Using 'break' in an in-line macro to exit from a loop that started
outside the macro will work, but is a bad programming practice.

Inside a macro, break n with the appropriate value of n should always be
used instead of breakall.

@@@@examples#Examples
Examples:
  for(i,run(100)){... compute x ...;if(x<0){print("x < 0");break;};...;}
If x ever becomes negative, the 'for' loop is terminated.
  for(i,run(10)){for(j,run(5)){...;if(x<0){break 2}}}
If x ever becomes negative, both 'for' loops are terminated.
@@@@______

@@@@see_also#Cross references
See also topics 'if', 'for', 'while', 'breakall', 'next', batch().
@@@@______

====breakall#control,syntax
%%%%
for(i,run(n)){if(x[i] < 0){breakall} .... }
for(i,run(n)){for(j,run(m)){if(x[i,j] < 0){breakall}}}
%%%%
'breakall' is used in 'while' and 'for' loops to exit prematurely from
any and all "enclosing" 'while' or 'for' loops.  Execution resumes
immediately after the '}' terminating the most inclusive 'while' or
'for' loop currently in effect.

'breakall' should normally not be used inside a macro, since if such a
macro were invoked in a loop at the prompt level, 'breakall' would exit
from that loop as well as any loops in the macro.  This would seldom be
what you want.  Instead, use 'break n', where n is a positive integer
specifying the number of loops to exit.  See 'break'.

It is an error to use 'breakall' outside of a loop.

In an evaluated string or out-of-line macro, 'breakall' will exit the
outermost loop that started inside the evaluated string or macro.  It is
an error if there is no such enclosing loop.  See evaluate() and
'macros'.

In an in-line macro (the default), 'breakall' will exit not only loops
which start in the macro, but also any loops which enclose the macro.
If this is not what is wanted (and it usually wouldn't be), use 'break
n', where n is the number of loops enclosing 'break' in the macro.
Use 'return' to exit from a macro prematurely.

@@@@example#Example
Example:
  Cmd> for(i,run(m)){
          for(j,run(n)){... compute x ...;if(x<0){breakall};}}

If x ever becomes negative, both 'for' loops are immediately terminated.
Using 'break' instead of breakall would mean that only the inner loop
(for(j,run(n)){...}) would be terminated.

@@@@see_also#Cross references
See also topics 'if', 'for', 'while', 'break', 'next', 'return'.
@@@@______

====breakif()#control,syntax
%%%%
for(i,run(n)){breakif(x[i] < 0) .... }
for(i,run(n)){for(j,run(m)){breakif(x[i,j] < 0, 2) ...}}
%%%%
@@@@usage#Usage
breakif(Logical) is equivalent to if(Logical){break;} .
breakif(Logical,n) is equivalent to if(Logical){break n;} .

It is implemented as a pre-defined in-line macro.  It can be used only
inside a loop and n must not exceed the number of containing loops.

@@@@example#Example
Example:
  Cmd> for(i,run(length(x))){breakif(abs(x[i]) > 3)}
computes the index i of the first element on vector x to exceed 3 in
absolute value.

@@@@see_also#Cross references
See also topics 'break', 'breakall', 'next'.
@@@@______

====callback_fun%#general,control
%%%%
Type userfunhelp(user_fun) for information on the structure of user
  functions.
Type userfunhelp(callback_fun) for information on the structure of user
  functions making "call backs" to MacAnova.
Type userfunhelp(arginfo_fun) for information on how to enable automatic
  checking of arguments to a user function.
%%%%
This topic is in file userfun.hlp.  Type
  userfunhelp(callback_fun)

It provides a brief introduction to the form of a user function that
makes "call backs" (executes functions internal to MacAnova).

Some other useful entries in userfun.hlp are arginfo_fun and user_fun.
Type
  userfunhelp()
for a complete list of entries.

====carapace#general
%%%%
Type help(carapace) for information about windowed versions of MacAnova
%%%%
Windowed forms of MacAnova from version 5.00 onwards use the Carapace
and wxWidgets libraries to provide graphical user interfaces.  This 
help topic describes features common to those versions.  

There are several other related help topics that you may wish to
explore.  Topic 'nongui' describes non-windowed MacAnova.  Topics
'dos_windows', 'macintosh', and 'unix' describe specifics for those
platforms.  Topics 'launching' and 'customize' describe the use of
command line options, MacAnova options, and initialization files.

Windowed forms of MacAnova allow multiple command/output and high
resolution graphics windows and also use menus, dialogs, the mouse,
and so forth in the standard way.  A command window has two panes,
a lower pane, into which commands are typed, and an upper pane,
into which results are printed. Output and graphics windows can be
printed and/or saved to files.

When you type into the command window, any unmatched quotes, braces,
brackets, or parentheses will be highlighted.  If you specify a
filename as "", then a dialog box will be opened to allow you to
select the file interactively.

@@@@clipboard#The Clipboard
Text in a command window can be copied to the clipboard.  Content of
a graphics window can be copied to the clipboard as a bitmap.  The
MacAnova variable CLIPBOARD is connected to text on the clipboard in
the sense that accessing CLIPBOARD returns a MacAnova string containing
the text content of the clipboard, and assigning to CLIPBOARD writes
text to the clipboard.

@@@@cmenus#Command Window Menus
File Menu Items
    Open              Open a text file in a new command window.
    Save              Save the output pane of this window to a file.
    Save Window As    Save, but allow a name change.
    Page Setup        Set up for printing.
    Print Window      Print the output pane of this command window.
    Interrupt         Stop processing the current MacAnova command.
    Restore           Restore a MacAnova workspace from a file.
    Save Workspace    Save your workspace to a file.
    Save Workspace As Save your workspace to a file, changing the name.
    Quit              Quit MacAnova

PLEASE NOTE: saving the window saves your output but not your data.
Saving the workspace saves your data but not your output.  You may
wish to do both.

Edit Menu Items
    Undo/Redo         Undo or redo last change in output pane.
    Cut               Cut text.
    Copy              Copy text.
    Paste             Paste text.
    Copy to Command   Copy the selection to the command pane
    Execute           Copy the selection to the command pane and execute
    Back History      Move back through command history
    Forward History   Move forward through command history

Windows Menu Items
    Hide              Hide this window.
    Close             Close this window.
    New               Open a new command window.
    Output Windows    A submenu allowing you to access command windows.
    Graph Windows     A submenu allowing you to access graphics windows.
    Set Font          Change the font in this command window.
    Scroll to Top     Scroll to the top of the output pane.
    Scroll to Bottom  Scroll to the bottom of the output pane.
    Move to Command   Move keyboard and pointer focus to the lower pane.

Help Menu Items
    Help              General help on MacAnova, or help on the selection.
    About             Information about MacAnova.

Keyboard equivalents.
There are keyboard equivalents for many of the menu commands.  For
example, up and down arrows in the command pane do backward and 
forward in the command history.

Button equivalents.
Each command window has six buttons across the bottom.  Five of
these implement the undo, execute, back history, forward history,
and interrupt menu items.  The sixth is Clear, which clears the text
in the command pane.

On the same row with the buttons are two status displays.  The first
indicates when MacAnova is processing a command by displaying the text
"Running".  The second tells you how far back you are in the command
history at any given point.
	
@@@@gmenus#Graphics Window Menus
File Menu Items
    Save Graph As     Save the graph as jpeg, tiff, png, or PostScript.
    Page Setup        Set up for printing.
    Print Window      Print the graph. 
    Interrupt         Stop processing the current MacAnova command.
    Quit              Quit MacAnova

Edit Menu Items
    Copy              Copy the graph to the clipboard as a bitmap.

Windows Menu Items
    Hide              Hide this window.
    Close             Close this window.
    Zoom in           Zoom in on the graph
    Zoom out          Zoom out on the graph
    Fit               Redraw the graph to fit the window exactly.
    Fit keep aspect   Redraw the graph but maintain the aspect ratio.
    Set aspect ratio  Set the aspect ratio for the graph.
    Output Windows    A submenu allowing you to access command windows.
    Graph Windows     A submenu allowing you to access graphics windows.



====cat()#variables,combining variables,character variables,null variables
%%%%
cat(x1,x2,...,xk [,KeyPhrases]) where x1, x2, ... all have the same
  type, REAL, LOGICAL, or CHARACTER, or are structures with components
  all of the same type
KeyPhrases can be labels:lab and/or silent:T, where lab is a CHARACTER
  scalar or vector.
%%%%
cat() is identical to vector().  See vector() for information on its
use.  See topic 'vectors' for general information on vectors.

The use of cat() is deprecated -- that is, it will continue to be
available for the immediate future, but at some point may be disabled.
Use vector() instead.

====cconj()#time series,complex arithmetic
%%%%
cconj(cx), cx a REAL matrix representing complex data
%%%%
@@@@usage#Usage
cconj(cx) returns the complex conjugates of successive pairs of columns
of the matrix cx, considered as the real and imaginary parts of complex
series.  The real and imaginary parts of the results are in alternating
columns.

When cx has an odd number, say 2*m-1, of columns, the last column is
interpreted as the real part of a complex series with zero imaginary
part.  In the result, an extra column of zeros is added, so the result
has 2*m columns representing m complex series with both real and
imaginary parts.

@@@@see_also#Cross references
See also hconj(), hreal(), himag(), creal(), cimag().

See topic 'complex' for discussion of complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====cdivc()#time series,complex arithmetic
%%%%
cdivc(cx1 [, cx2]), cx1 and cx2 REAL matrices representing complex data
%%%%
@@@@usage#Usage
cdivc(cx1, cx2) computes the element wise complex ratio of fully complex
(pairs of columns constitute real and imaginary parts) matrices cx1 and
cx2.  When either of cx1 or cx2 has an odd number of columns, it is
augmented with a column of zeros before division.

Any ratio of the form (0 + 0i)/(0 + 0i) is returned as 0 + 0i.  The ratio
of a non-zero element of cx1 and 0 + 0i is MISSING + MISSING*i.

cdivc(cx) is equivalent to cdivc(cx,cx), returning a result all of whose
elements are 1 + 0i, except for (0 + 0i)/(0 + 0i) ratios which are 0 +
0i.

When nrows(cx1) > 1 and nrows(cx2) > 1, nrows(cx1) = nrows(cx2) is
required.  Otherwise, the single row in the short argument is implicitly
duplicated to match the number of rows in the other argument.

When cx1 represents a single complex series (ncols(cx1) <= 2), that
series is divided by all the series in cx2.  Similarly when ncols(cx2)
<= 2, all the series in cx1 are divided by cx2.

@@@@examples#Examples
Examples:
  When ncols(cx1) = 2 and ncols(cx2) = 5, cdivc(cx1,cx2) is eqivalent to
  cdivc(hconcat(cx1,cx1,cx1),hconcat(cx2,rep(0,nrows(cx2)))).

  cdivc(1,cx) computes the complex reciprocal of cx.

@@@@see_also#Cross references
See also cdivcj(), hdivh(), hdivhj(), cprdc(), cprdcj(), hprdh(),
hprdhj(), hconcat(), rep(), nrows(), ncols().

See topic 'complex' for discussion of complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====cdivcj()#time series,complex arithmetic
%%%%
cdivcj(cx1 [, cx2]), cx1 and cx2 REAL matrices representing complex data
%%%%
@@@@usage#Usage
cdivcj(cx1, cx2) computes the element wise complex ratio of fully
complex (pairs of columns constitute real and imaginary parts) matrices
cx1 and cconj(cx2).  When either cx1 or cx2 has an odd number of
columns, it is augmented with a column of zeros before division.

Any ratio of the form (0 + 0i)/(0 + 0i) is returned as 0 + 0i.  The ratio
of a non-zero element of cx1 and 0 + 0i is MISSING + MISSING*i.

cdivcj(cx) is equivalent to cdivcj(cx,cx).

When nrows(cx1) > 1 and nrows(cx2) > 1, nrows(cx1) = nrows(cx2) is
required.  Otherwise, the single row in the short argument is implicitly
duplicated to match the number of rows in the other argument.

When cx1 represents a single complex series (ncols(cx1) <= 2), that
series is divided by the complex conjugates of all the series in cx2.
Similarly when ncols(cx2) <= 2, all the series in cx1 are divided by
cconj(cx2).

@@@@examples#Examples
Examples:
  When ncols(cx1) = 2 and ncols(cx2) = 5, cdivcj(cx1,cx2) is eqivalent
  to cdivcj(hconcat(cx1,cx1,cx1),hconcat(cx2,rep(0,nrows(cx2)))).

  cdivcj(1,cx) computes the complex reciprocal of cconj(cx).

@@@@see_also#Cross references
See also cdivc(), hdivh(), hdivhj(), cprdc(), cprdcj(), hprdh(),
hprdhj(), cconj(), hconcat(), rep(), nrows(), ncols().

See topic 'complex' for discussion of complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====ceiling()#transformations
%%%%
ceiling(x), x REAL or a structure with REAL components
%%%%
@@@@usage#Usage
ceiling (x) rounds the elements of the REAL variable x to the next
integer in the positive direction, producing a vector, matrix, or array
with the same shape as x.

@@@@example#Example
Example:
  Cmd> ceiling(vector(3.1416, -3.1416, 12))
  (1)           4          -3          12

@@@@argument_too_large#Argument too large
When x > 4503599627370495 or x < -4503599627370495, ceiling(x) is set to
MISSING because of the impossibility of exact representation of integers
beyond these limits.  These limits may be different on some computers.

@@@@structure_argument#Structure argument
When x is a structure consisting of REAL components, so is ceiling(x).
If the i-th component of x is xi, the i-th component of ceiling(x) is
ceiling(xi).

@@@@see_also#Cross references
See also topics floor(), round(), 'structures'.
@@@@______

====cellstats()#descriptive statistics,anova
%%%%
cellstats(Term), Term a CHARACTER scalar of form "A.B. ...", where A, B,
   ...  are factors in current GLM model.
%%%%
@@@@usage#Usage
cellstats(Term) computes statistics for each cell of the multiway layout
indicated by the term in the CHARACTER variable Term. The term must be
made of factors in the model used by the most recent GLM (generalized
linear or linear model) command such as regress(), anova(), or
poisson().  It omits all cases for which there is any MISSING data in
either the left or right hand sides of the model.

@@@@difference_from_tabs#Difference from tabs()
cellstats() and tabs() do almost the same thing and generally tabs() is
to be preferred.  When Term is, say, "a.b.c" where a, b, and c are
factors in the most recent GLM, and y is the response variable in the
model, cellstats(Term) is almost equivalent to tabs(y, a, b, c).

cellstats() and tabs() will differ only when (a) the response variable y
is multivariate (has more than 1 column) and (b) there are MISSING data
in y.  cellstats() omits completely any row of y that contains any
MISSING data; tabs() uses all non-MISSING data available and thus the
cell count can differ among the columns of y.  Except in this case, you
should probably use tabs() in preference to cellstats() since tabs() has
additional options and can be used independently of any GLM command.
Even in this case, tabs() is preferable if you want cell statistics that
use all the data.

Of course, both cellstats() and tabs() omit all cases for which any of
the factors are MISSING (how could they determine the cell?).

@@@@example#Example
Example:
  Cmd> anova("y=a+b+c+b.c") ; cellstats("b.c") # or tabs(y,b,c)
gives cell statistics for the b.c term.

@@@@see_also#Cross references
See also topics 'glm', tabs().
@@@@______

====cft()#time series,complex arithmetic
%%%%
cft(cx [,divbyT:T]), cx a REAL matrix representing complex data
%%%%
@@@@usage#Usage
cft(cx) where cx is a REAL vector or matrix, computes the fully complex
form of the discrete Fourier transforms of successive pairs of columns
of cx, considered as the real and imaginary parts of complex series.
The real and imaginary parts of the results are in alternating columns.

Any MISSING values in cx are replaced by 0 in computing the result and a
warning message is printed.

cft(cx,divbyt:T) does the same except the transform is divided by the
number of rows of cx.

@@@@inverse_transform#Inverse transform
cconj(cft(cconj(cx),divbyt:T)) is the inverse of cft() in the sense that
cx and cconj(cft(cconj(cft(cx)),divbyt:T)) are equal except for rounding
error.

@@@@limitation_on_length#Limitation on length
The largest prime factor of nrows(cx) must not exceed 29.  You can use
primefactors() to find the maximum factor of nrows(cx) and goodfactors()
to find a length >= nrows(cx) which has no prime factors > 29.  In
addition, the product of all the "unpaired" prime factors can't be too
large.  For example N = 3*5*7*11*13*17*M^2 = 255255*M^2, where M is an
integer, breaks the algorithm and hence is not allowed.

@@@@see_also#Cross references
See topic 'complex' for discussion of complex matrices in MacAnova.

See also hft(), rft(), cconj(), primefactors(), goodfactors().

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====changestr()#structures
%%%%
changestr(Struc,name,x), Struc a structure, name a CHARACTER  scalar, x
  a defined variable
changestr(Struct,n,x), integer n, 1 <= n <= ncomps(Struct) + 1
changestr(Struct,name:x)
changestr(Struc, -n), n a positive integer
%%%%
@@@@change_component_by_name#Change component by name
changestr(Str,Name,x) makes a copy of structure Str except that the
value of component Name is changed to x.  Name must be a quoted string
or CHARACTER scalar of no more than 12 characters.  It is an error if
Name contains a space, '$' or any "control character" (ASCII code <= 31
or 127).  If there is no component with name Name, x will be added as a
new component.  It will have name Name unless x is a keyword phrase

changestr(Str,Name,newname:x) does the same, except the changed or added
component has name 'newname'.

changestr(Str,compname:x) is the same as changestr(Str,"compname", x).
compname must have no more than 10 characters.

If you want to change a named component of a structure, say component
var of structure stats, it is better to use 'stats$var <- x' than
stats <- changestr(stats,"var", x).

@@@@change_component_by_number#Change component by number
changestr(Str,CompNumber,x), where CompNumber is a positive integer,
does the same, except the component to be changed is specified by number
rather than by name.  When CompNumber = ncomps(Str) + 1, a new component
with value x is added.  It is an error if CompNumber > ncomps(Str)+1.

changestr(Str,CompNumber,newname:x) does the same except the changed or
added component will have name 'newname'.

To change a component of a structure by number, it is preferable to us
Str[CompNumber] <- x rather than Str <- changestr(Str,CompNumber,x).

Moreover, you can change more than one component at a time by assigning
to subscripts:
  Cmd> Str[run(2)] <- vector(Pi,PI^2)
changes components and and 2 of Str without changing there names.

@@@@deleting_component#Deleting component
changestr(Str,-CompNumber) produces a new structure omitting component
CompNumber.  It is illegal to delete the only component of a structure.

Preferable to this usage is Str[-CompNumber].  Moreover, you can omit
several components by, say, Str[-run(2)].

@@@@modificication_using_assignment#Modificication using assignment
When Str is a structure with a component Name, Str$Name <- x changes
component Name, without making a temporary copy of Str.

When J is a positive integer <= ncomps(Str), Str[J] <- x changes
component J, without making a temporary component of Str.  You can
change more than component of Str when J is a vector of subscripts.  See
topic 'assignment'.

@@@@examples#Examples
Examples:  In each of the following groupings, all the commands return
the same structure:
  Cmd> changestr(structure(a:run(10),b:"Hello"),"a",PI)
  Cmd> changestr(structure(a:run(10),b:"Hello"),1,PI)
  Cmd> structure(a:PI,b:"Hello")

  Cmd> changestr(structure(a:run(10),b:"Hello"),"a",pi:PI)
  Cmd> changestr(structure(a:run(10),b:"Hello"),1,pi:PI)
  Cmd> structure(pi:PI,b:"Hello")

  Cmd> changestr(structure(a:run(10),b:"Hello"),3,c:"Dolly")
  Cmd> changestr(structure(a:run(10),b:"Hello"),c:"Dolly")
  Cmd> structure(a:run(10),b:"Hello",c:"Dolly")

  Cmd> changestr(structure(a:run(10),b:"Hello"),-1)
  Cmd> structure(b:"Hello").

@@@@see_also#Cross references
See also topics 'structures', 'keywords', structure(), strconcat().
@@@@______

====cholesky()#matrix algebra
%%%%
cholesky(x [,pivot:T or force:T , nonposok:T]), x a positive definite
  square REAL matrix with no MISSING values
%%%%
@@@@usage#Usage
cholesky(A) returns the Cholesky decomposition of the positive definite
REAL symmetric matrix A.  Its value is the REAL upper triangular matrix
r of the same size as A such that r' %*% r = A.  It is an error if A is
not positive definite.

@@@@keyword_nonposok#Keyword 'nonposok'
cholesky(A, nonposok:T) does the same, except that a non positive
definite A is not considered to be an error, but results a value of NULL
being returned.  This makes it possible for a macro to take corrective
action when a matrix is not positive definite.  See topics 'macros' and
'NULL'.

@@@@keyword_pivot#Keyword 'pivot'
cholesky(A,pivot:T [,nonposok:T]) reorders the rows and columns as the
computation proceeds so as to obtain the most stable computation.  It
returns a structure with components 'r', a REAL upper triangular matrix,
and 'pivot', a REAL vector of integers describing the reordering.  After
result <- cholesky(A,pivot:T), result$r' %*% result$r should equal
A[result$pivot, result$pivot] except for rounding error.

@@@@keyword_force#Keyword 'force'
cholesky(A,force:Vec [,nonposok:T]), where Vec is a REAL vector whose
length is nrows(A), enables pivoting, but allows some control on
reordering.  The elements of Vec should be 1, -1, or 0, since only the
signs are used.  Before factoring, rows and columns of A, if any, with
index j such that Vec[j] > 0 are moved to rows and columns 1, 2, ...,
(initial columns) but are not further moved.  All rows and columns with
Vec[j] < 0 are moved to rows and columns nrows(A), nrows(A) - 1, ...,
(final columns) but are not further moved.  Rows and columns, if any,
with Vec[j] == 0 (pivoted columns), are free to be reordered, but will
follow the initial columns and precede the final columns.  Again the
result is a structure with components 'r' and 'pivot'.

@@@@see_also#Cross references
See also qr().
@@@@______

====chplot()#plotting
%%%%
chplot(x,y [, symbols:c] [, add:T, lines:T, impulse:T] [,graphics
  keyword phrases]), where x is a REAL vector or scalar, y is a REAL
  vector or matrix and c is a integer or CHARACTER scalar, vector, or
  matrix
chplot([Graph,] [x,y, symbols:c], keys:str), str a structure whose
  component names are graphics keywords such as 'add', 'lines' and
  'impulse'
%%%%
@@@@usage#Usage
chplot(x,y,symbols:c) makes a scatter plot of REAL vector or matrix y
versus REAL vector x using plotting symbols as specified by CHARACTER or
REAL vector c.

It is not an error when x or y is NULL; a warning message is printed and
no plotting occurs.

For backward compatibility with earlier versions, you can omit keyword
'symbols', as in chplot(x,y,c).

chplot(Struc,symbols:c), where Struc is a structure with at least two
REAL components, is equivalent to chplot(Struc[1], Struc[2], symbols:c).
For example, chplot(x,y,symbols:c) and chplot(structure(x,y),symbols:c)
are equivalent.  Any components beyond the first two are ignored.

@@@@graph_variable_argument#Graph variable argument
chplot(graph,x,y,symbols:c) or chplot(graph,Struc,symbols:c), where
graph is a GRAPH variable, draws the plot encapsulated in graph, adding
to it the new information.  See topic 'graph' for details on adding
information to a plot.

@@@@symbols_used#Symbols used
When c is REAL, each element c[i] must be an integer with 0 <= c[i] <=
999 and the plotting symbol will be the number centered at the plotting
point.

When c is a CHARACTER scalar with value "###", the characters plotted
are the same as when symbols:c is omitted; see below.

When c is CHARACTER other than the scalar "###", up to 3 characters from
each c[i] will be drawn centered at the plotting point.

@@@@default_symbols#Default symbols
Argument symbols:c may be omitted.  In this case the default plotting
characters are as follows:
  y a vector:                   The row number of an element y
  y a matrix with ncols(y) > 1: The column number of an element

@@@@add_keyword#Keyword 'add'
chplot(x,y [,symbols:c], add:T, ...) does the same as chplot(LASTPLOT,
x, y [,symbols:c), that is, plotted points are combined with the data
already in LASTPLOT.

@@@@lines_impulse_and_dumb_keywords#'lines', 'impulse' and 'dumb' keywords
chplot([graph,] x,y, lines:T [,symbols:c]) makes a character plot,
connecting the points by lines similarly to lineplot().

chplot([graph,] x,y, impulse:T [,symbols:c] [,lines:T]) does the same
except that vertical lines will be drawn to the points from the x = 0
line.

When option 'dumbplot' has been set False (see subtopic
'options:"dumbplot"'), the plot will be a low resolution plot unless
'dumb:F' is an argument.

@@@@symbol_variable_shape#Symbol variable shape
When c has more than 1 column then you must have ncols(c) = ncols(y) and
the elements in c[,j] will be used to plot y[,j], reusing the rows of c
cyclically if nrows(c) < nrows(y).

When c is a vector of length ncols(y), c[j] will be used to plot all
elements of the column y[,j]

Otherwise, if c is a vector with length(c) != ncols(y), c[i] will be
used to plot all elements in the row y[i,], reusing the rows of c
cyclically if nrows(c) < nrows(y).

@@@@drawn_plotting_symbols#Drawn plotting symbols
                         Drawn plotting symbols
When the first character of an element of a CHARACTER c has ASCII code V
between 1 and 31, it designates a specially drawn character.  There are
8 basic shapes in three sizes, diamond (V=1, 9, 17), plus sign (V=2, 10,
18), square (V=3, 11, 19), cross (V=4, 12, 20), triangle (V=5, 13, 21),
star (V=6, 14, 22), dot (V=7, 15, 23) and circle (V=8, 16, 24).  Codes
1 - 8 are the standard sizes; codes 9 - 16 are about 2/3 standard size
and 17 - 24 are about 1/2 standard size.  There is only one size dot.
Codes 25 - 31 "wrap around" to 1 - 7.

You can specify these special ASCII codes using quoted strings "\1",
"\2", "\3", "\4", "\5", "\6", "\7", "\10", "\11", ... ,"\17", "\20",
..., "\27", "\30", ..., "\37".  The digit or digits are the octal
representations of the codes.  For example, "\3" represents an ASCII 3
and specifies a standard size square, "\10" represents an ASCII 8 and
specifies a standard size circle, and "\27" represents 22, the smallest
size star.  They can also be specified using escaped hexadecimal codes
"\x01", "\x01", "\x02", ..., "\x09", "\x0a", ..., "\x1f".

You can also specify these codes by name, using makesymbols().  For
example, chplot(x,y,symbols:makesymbols("diamond",medium:T)) makes the
same plot as chplot(x,y,symbols:"\11").  See makesymbols() for details.

See topic 'graphs' for the use of a scalar or length 2 vector for x.

@@@@add_keyword#Keyword 'add'
Use keyword phrase 'add:T' or commands addchars(), addlines(),
addpoints() and addstrings() to add information to a plot.

@@@@keywords#Keywords
Keywords 'dumb', 'lines', 'linetype', 'thickness', 'impulse', 'xmin',
'xmax', 'ymin', 'ymax', 'logx', 'logy', 'xlab', 'ylab', 'title',
'xaxis', 'yaxis', 'borders', 'ticks', 'xticks', 'yticks', 'xticklen',
'yticklen', 'xticklabs', 'yticklabs', 'height', 'width', 'pause',
'silent' and 'notes' may be used as for other plotting commands.  See
topics 'graph_keys', 'graph_border' and 'graph_ticks'

@@@@see_also#Cross references
See topic 'graph_assign' for information on another way to make plots.

@@@@keys_keyword#Keyword 'keys'
chplot([Graph,] keys:structure(x:x,y:y,symbols:c [other keyword
phrases)) is equivalent to chplot([Graph,] x:x,y:y, symbols:c [other
keyword phrases]).  See topic 'graph_keys' for details.

@@@@file_keywords#File keywords
See topic 'graph_files' for information on how to save a plot in a file
using keywords 'file', 'new, 'ps', 'screendump', and 'epsf'.
@@@@______

@@@@examples#Examples
Examples:
  Cmd> chplot(x,y,symbols:"*")
makes a plot of y vs x with "*" as plotting symbol.

Suppose x[,1] contains integers 1, 2, or 3.  Then

  Cmd> chplot(X2:x[,2],X3:x[,3], symbols:vector("A","B","C")[x[,1] ],\
        title:"X3 vs X2")

makes a plot of column 3 of x against column 2, using plotting symbols
"A", "B", or "C", according as the value in column 1 of x is 1, 2 or 3.
Axes are labeled 'X2' and 'X3' and a title is printed.

  Cmd> chplot(X:1,run(20)^(.2*run(5)'),\
        symbols:vector(".2",".4",".6",".8","1.")', ylab:"Powers of X",\
        title:"X^.2, X^.4, X^.6, X^.8, and X",lines:T)

draws line connected plots of x^.2, , x^.4, x^.6, x^.8 and x vs x, using
plotting symbols ".1", ".4", ...,"1.0" for each line.  X:1 is equivalent
to X:run(20).  See subtopic graphs:"specification_of_data" for details.

@@@@see_also#Cross references
See also topics 'graphs', plot(), lineplot(), showplot(), addchars(),
addlines(), addpoints(), colplot(), rowplot(), tek(), vt().
@@@@______

====cimag()#time series,complex arithmetic
%%%%
cimag(cx), cx a REAL matrix representing complex data
%%%%
@@@@usage#Usage
cimag(cx) computes the imaginary part of the fully complex matrix cx.
For example, cimag(matrix(run(10),5)) is vector(6,7,8,9,10).

@@@@see_also#Cross references
See also hconj(), cconj(), hreal(), himag(), creal().

See topic 'complex' for discussion of complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====CLIPBOARD#syntax,character variables,input,output
%%%%
CLIPBOARD <- x   or   x <- CLIPBOARD  or  vecread(string:CLIPBOARD)
x <- fromclip([ncols]), integer ncols > 0
toclip(x), x REAL scalar, vector, matrix or array
SELECTION <- x  or  x <- SELECTION (GTK only)
Type help(CLIPBOARD) for more information.
%%%%
@@@@special_variable_CLIPBOARD#Special variable CLIPBOARD
A special CHARACTER variable CLIPBOARD is always defined.  When used in
an expression or as an argument to a function, CLIPBOARD behaves just
like any other variable.  It can be printed, written to a file, or
assigned to a regular variable.

In windowed versions, CLIPBOARD allows direct access to the system
Clipboard.

@@@@assignment_to_CLIPBOARD#Assignment to CLIPBOARD
CLIPBOARD <- x assigns a CHARACTER representation of x to CLIPBOARD.  x
must be a CHARACTER, REAL or LOGICAL variable.

CLIPBOARD[1] <- x and CLIPBOARD[T] <- x do the same, provided x is a
scalar variable.  It is an error if x is not a scalar.

CLIPBOARD[rep(1,k)] <- x is permissible, in which case x must be a
vector of length k and CLIPBOARD will contain a CHARACTER representation
of x[k].

In the windowed versions, CLIPBOARD <- x and CLIPBOARD[1] <- x copy
the new value of CLIPBOARD to the system Clipboard.  And when any text
is copied to the system Clipboard using the Edit Menu in MacAnova or
any other program, that text becomes the value of CLIPBOARD.

In non-windowed versions, CLIPBOARD <- x and CLIPBOARD[1] <- x do
nothing beyond setting CLIPBOARD to CHARACTER representation of
x (to x when x is CHARACTER).

@@@@details
                Details of the CHARACTER representation
After CLIPBOARD <- x, the contents of variable CLIPBOARD (and of the
system Clipboard in the Windowed versions) are as follows:

  When x is a CHARACTER scalar, CLIPBOARD will contain that scalar.
  This is also the case after CLIPBOARD[1] <- x.

  When x is a REAL or LOGICAL scalar, CLIPBOARD will contain a character
  representation of x. This is also the case after CLIPBOARD[1] <- x.
  For example CLIPBOARD is "3.1415926535897931" after either CLIPBOARD
  <- PI or CLIPBOARD[1] <- PI and is "T" after CLIPBOARD <- PI > 3 or
  CLIPBOARD[1] <- PI > 3.

  When x is a vector of length N, CLIPBOARD will contain N lines
  separated by "\n", with line i containing a x[i], when x is CHARACTER,
  or a CHARACTER representation of x[i] otherwise.

  When x is a matrix, CLIPBOARD will contain nrows(x) lines, with line i
  containing CHARACTER representations of x[i,j], j=1,...ncols(x),
  with the elements of each row separated by the tab character "\t".

  When x is an array with 3 or more dimensions greater than 1, it is
  treated as if it were a matrix with nrows(x) = first dimension > 1.

Stated more technically, the value of CLIPBOARD after CLIPBOARD <- x is
what would be produced by
   Cmd> CLIPBOARD <- paste(x,multiline:T,missing:"?",sep:"\t",\
                linesep:"\n", format:"0.17g")

See topic paste() for more information on paste(x,multiline:T,...).

Since MISSING is coded as '?', after CLIPBOARD <- x, where x is REAL
vecread(string:CLIPBOARD), should produce vector(x), including MISSING
values.
@@@@______

Two pre-defined macros, toclip() and fromclip(), are useful when working
with CLIPBOARD.  In particular, toclip() allows for different coding of
MISSING and user specified field separators.  See topics fromclip() and
toclip().

@@@@value_of_CLIPBOARD#Value of CLIPBOARD
In the windowed versions, because the value of CLIPBOARD is whatever
text the system Clipboard currently contains, CLIPBOARD may not be the
same as what was most recently assigned to it.  This can happen because
of subsequent use of Edit menu items in MacAnova or another program.
This feature allows easy importing of data from other programs,
especially from spreadsheets.  See topic fromclip().

Similarly, in the windowed versions you can easily export data from
MacAnova to another application like a spreadsheet by assigning the
value of a variable to CLIPBOARD.  See toclip().

You can free up the memory used by the contents of CLIPBOARD by
delete(CLIPBOARD).  This has no effect on any system Clipboard.

You probably should not use CLIPBOARD as a name for a structure
component or as a keyword on a computer with an actual Clipboard, as
every mention of CLIPBOARD, even in contexts like str$CLIPBOARD or
CLIPBOARD:T, refreshes special variable CLIPBOARD with stuff from the
Clipboard.

@@@@selection_in_gtk
                      Variable SELECTION in GTK
In GTK, selecting text with the mouse provides another method of
communicating between programs.  Briefly, if you select text and then
click in a window using the middle button on the mouse, what was
selected is inserted there.  The GTK version of MacAnova has a special
CHARACTER variable SELECTION which is connected to the current selection
in the same way CLIPBOARD is connected to the Clipboard.  Immediately
after
  Cmd> SELECTION <- x
if you click in a window with the middle button, a character
representation of x is "pasted" into the window.  SELECTION[1] <- x is
permissible if x is a scalar.

Similarly, if you select text in a window,
  Cmd> charx <- SELECTION
creates a CHARACTER variable charx containing the text; if the text is
numerical data,
  Cmd> x <- vecread(string:SELECTION)
creates a REAL vector x.  Use of this feature is somewhat tricky, since
clicking in a window can change the selection.  When you assign
something to SELECTION, you should retrieve it with a middle button
click before doing anything else.  And if you want to assign from or
read from SELECTION, you should type the command without a terminating
Enter, then select what you want to copy, click on the frame of the
MacAnova window, and then press Ctrl+E followed by Return to execute the
command.

@@@@see_also#Cross references
See also topics vecread(), read(), matread(), macroread().
@@@@______

====clipreaddata#input
%%%%
clipreaddata(name1,...,namek [,factors:T] [,keyword phrases]),
  name1,... names, quoted or unquoted variable names
clipreaddata(vector("name1",...,"namek") [,factors:F][,keyword phrases])
clipreaddata([factors:F] [,keyword phrases])
%%%%
@@@@introduction#Introduction
Macro clipreaddata() creates data vectors from information on the
clipboard.  It uses macro readdata() to "read" the clipboard and its
usage is identical, except that you don't specify a file name.  Like
readdata(), it can handle data sets in which some data columns are
non-numerical and can get variable names from the first line of the
clipboard.

Any line on the clipboard that starts with skip character '#' is
automatically skipped and is echoed to output by default.

clipreaddata() is particularly useful for importing data from a spread
sheet program, particularly if the first line contains variable names.
In the spread sheet program, you select a rectangular set of cells
containing numbers and copy them to the Clipboard by selecting Copy on
the Edit menu.  After switching to MacAnova, you then use clipreaddata()
to create MacAnova variables from the data in each column you selected.
For instance, if the selection contains 10 rows and 5 columns of data,
clipreaddata() will make 5 length 10 vectors.  Caution: Before copying
to the clipboard, fill any empty cells with one of "?", "*", "." or
"NA".  clipreaddata() will read these as MISSING values.

@@@@usage#Usage
clipreaddata(name1,name2,...,namek) uses vecread() to read one or more
columns of data from variable CLIPBOARD, creating variables.  name1,
name2, ..., namek.  The variable names can be either quoted ("weight")
or unquoted (weight).

Text on the clipboard should consist of k columns of "words" separated
by spaces, commas or tabs.  A column consisting entirely of numbers,
possibly with MISSING values (indicated by '?', '.', '*' or 'NA') is
read as a REAL vector.  A word is any set of consecutive characters not
including a comma, space or tab.

@@@@non_numerical_data#Non numerical data
When the first data item in a column is not a number or a code for
MISSING, the entire column is normally read as a factor, with a level
for each distinct word in the column.  The factor has the original words
in the file as row labels.

clipreaddata(name1,...,factors:F) does the same except a variable
starting with a non-numerical word is read as a CHARACTER vector rather
than translated into a factor.

@@@@names_from_first_line#Names from first line
clipreaddata([,factors:T]) does the same except the names for the
variables are assumed to be in the first non-skipped line of the
clipboard with the data starting in the second non-skipped line.
@@@@______

For all usages, the number of variable names, whether given as arguments
or taken from the first line of the clipboard, must divide the total
number of data values.  And of course the names must be legal MacAnova
variable names.

By default, for each variable, clipreaddata() prints a line containing
the variable name and information on its type, REAL, factor or
CHARACTER.  You can suppress this by including 'quiet:T' as an argument.

@@@@keywords#Keywords
You can use most vecread() keywords 'quiet', 'silent', 'stop', 'skip',
'skipthru', 'go', 'quiet', 'echo', and 'n', but not 'bypass', 'bywords',
'bylines', 'bychars', 'byfields' and 'realorchar'.  See topic
'vecread_keys'.

@@@@see_also#Cross references
See also fromclip(), toclip(), readcols(), vecread(), 'vecread_files'.
@@@@______

====clipwritedat()#output
%%%%
clipwritedat(x1,x2,... [,missing:M] [, putNames:F] \
  [,fieldwidth:w or format:fmt]), vectors x1, x2, ..., all with same
  length, CHARACTER scalars M, fmt, integer w > 0
%%%%
@@@@introduction#Introduction
clipwritedat() is a macro designed to copy to the clipboard vectors of
arbitrary in columnar form.  By default, the columns are headed by the
variable names.

@@@@usage#Usage
clipwritedat(x1,x2,...) transforms data vectors x1, x2, ... to character
form and then puts them side by side as columns in special variable
CLIPBOARD.  In windowed systems this also copies them to the system
clipboard.  Effectively, it sets CLIPBOARD to an "image" of the file
that would be written by writedata(fileName, x1, x2,...).

x1, x2, ... can be of any type.  If any vector is a factor and has row
labels consistent with the factor levels, the row labels are written
instead of the factor levels.

REAL data are formatted using the current default format as returned
by getoptions(format:T), except that integer values are written as
integers with no decimal point.

CHARACTER data is written right justified in a field whose width is
taken from the default format.

LOGICAL data are written as "T" or "F" and then written like CHARACTER
data.

MISSING values are written as "?".

If any data vector is specified by a keyword phrase (x1:X[,1], for
example), the keyword is used as the vector name.  For this usage, the
keyword may not be 'keep', 'new', 'fieldwidth' or 'missing'.

@@@@keywords#Keywords
The keywords for clipwritedat() are the same as those for writedata(),
except that 'new' is ignored.  See writedata() for details.

@@@@see_also#Cross references
See also clipreaddata(), fromclip(), toclip(), 'clipboard'.

====cluster()#multivariate analysis
%%%%
cluster(x [, nclust:n, standard:F, method:name, keep:charVec, print:T,\
  tree:T or F, classes:T or F, reorder:T]), x a REAL matrix, name a
  character scalar (one of "single", "complete", "average", "ward",
  "mcquitty", "centroid", or "median"), charVec a CHARACTER vector
  with elements "all", "classes", "criterion", or "distances"
cluster(dissim:d [, ...]), d a square REAL matrix
cluster(similar:s [, ...]), s a square REAL matrix
%%%%
@@@@usage#Usage
cluster(x) performs a hierarchical cluster analysis of cases (rows) of
the data matrix x.  The default method is average linkage and the
default maximum number of clusters described in the output is 9.  It
produces a table of cluster membership with one line per case and a
dendrogram, with the join points labeled with the value of the criterion
used.  There must be at least 2 rows in x.

Distances between cases in x are computed as squared Euclidean distance
after standardization by dividing by standard deviations.
Standardization can be suppressed by including 'standard:F' as an
argument.  NOTE: This is a change in behavior of cluster() from version
3.1 to version 3.3.

@@@@dissim_and_similar_keywords#Keywords 'dissim' and 'similar'
cluster(dissim:d) uses the upper triangle of the square matrix d as
dissimilarity or distance measure.  Matrix d must have at least 2 rows
and is treated algorithmically as if it were unsquared Euclidean
distance.

cluster(similar:s) uses the upper triangle of the square matrix s as a
similarity matrix.  Matrix sqrt(2*(max(vector(s))-s)) is used as a
distance matrix.  Matrix s must have at least 2 rows.

                          Other Keywords
Keyword phrase  Default  Meaning
@@@@method_keyword#Keyword 'method'
  method:Name "average"  The clustering method used.  Legal values are
                         "ward", "single", "complete", "average",
                         "mcquitty", "median" and "centroid".
                         Name must be a quoted string or CHARACTER
                         variable.

@@@@nclust_keyword#Keyword 'nclust'
  nclust:m     9         The number (>= 2) of clusters to be
                         described in the output.  When m > 25, the
                         class membership table requires more than 80
                         columns for printing, and if m > 22 the
                         dendrogram requires more than 80.  m > 50 is
                         illegal when either the class membership table
                         or the dendrogram is to be printed.

@@@@standard_keyword#Keyword 'standard'
  standard:F     T       suppresses the standardization of the data
                         matrix to unit standard deviations before
                         computing distances.  Not legal with 'dissim'
                         or 'similar'.

@@@@distance_keyword#Keyword 'distance'
  distance:Dname "euclid" Specifies the distance measure used to label
                         the dendrogram.  Legal values are "euclid" and
                         "euclidsq". It has no effect on the clustering
                         produced.  Dname must be a CHARACTER variable
                         or quoted string.  Not legal with keywords
                         'dissim' or 'similar'.

@@@@keep_keyword#Keyword 'keep'
  keep:charVec  none     Specifies which, if any, results should be
                         returned as the value of cluster().  charVec
                         must be a quoted string or a CHARACTER vector
                         or scalar.  Legal values for elements of
                         charVec are "distances" (the computed distances
                         are returned), "classes" (the computed n by
                         nclust-1 class membership matrix is returned),
                         "crit" (the criterion values at each of the
                         final nclust - 1 merges are saved), and "all"
                         (all three are returned).  When only one item
                         is to be returned, it is returned as a matrix
                         or vector.  Otherwise, items are components in
                         a structure with names 'distances', 'classes',
                         and 'criterion'.  The use of 'keep' suppresses
                         printing the table of class membership and the
                         dendrogram, unless print:T, tree:T, or
                         classes:T are arguments.  When 'keep' is not
                         used, cluster() has a NULL value.

@@@@print_keyword#Keyword 'print'
  print:T                Forces printing output, even when 'keep' is
                         used.  Default is F when 'keep' is used;
                         otherwise the default is T.

@@@@tree_keyword#Keyword 'tree'
  tree:T                 Forces printing of dendrogram.
  tree:F                 Suppresses printing of dendrogram.
                         Default is F when 'keep' is used; otherwise T.
                         Must come later than 'keep' in argument list.

@@@@classes_keyword#Keyword 'classes'
  classes:T              Forces printing of table of class membership.
  classes:F              Suppresses printing of table of class
                         membership.  Default is F when 'keep' is used;
                         otherwise T.  Must come later than 'keep' in
                         argument list.

@@@@reorder_keyword#Keyword 'reorder'
  reorder:T     F        Directs that the rows of the printed table of
                         class membership be reordered so that cases in
                         the same clusters are adjacent.  It does not
                         affect the returned value if keep:"classes"
                         appears.  The reordering is the same as that
                         implied in the dendrogram.  A warning message
                         is printed if you use reorder:T together with
                         classes:F.

@@@@example#Example
Example:
  Cmd> results <- cluster(x,nclust:15,keep:vector("classes","crit"),\
        method:"median",classes:T, reorder:T)
computes the last 15 stages of clustering, using the so called median
method, returns the class membership table and the criterion in a
structure, and prints the reordered class membership table.
@@@@______

====cmplx()#time series,complex arithmetic
%%%%
cmplx(Re,Im), Re and Im REAL matrices with same size and shape.
cmplx(Re)
%%%%
@@@@usage#Usage
cmplx(re,im) combines matrices re and im considered as the real and
imaginary parts of a complex matrix. The j-th columns of re and im
become the 2j-1-th and 2j-th columns of the result.  Re and im must have
the same size and shape and the output has the same number of rows and
twice the columns.  For example, if re and im are both 5 by 2,
cmplx(re,im) is equivalent to hconcat(re[,1],im[,1],re[,2],im[,2]).

cmplx(re) is equivalent to cmplx(re,0*re), that is, it produces a
complex matrix with 0 imaginary part.

@@@@see_also#Cross references
See topic 'complex' for discussion of complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====coefs()#glm,anova,regression
%%%%
coefs([Term] [, errorTerm:ErrorTerm, se:T, coefs:F, byterm:F,
  silent:T]), Term a CHARACTER scalar, a positive integer, or a factor
  or variate in the current GLM model, ErrorTerm a CHARACTER scalar or
  positive integer.  Use byterm:F only when Term and coefs:F omitted,
  and se:T included
%%%%
@@@@usage#Usage
coefs(Term) returns the model effects or regression coefficients for
term Term in the current GLM model.  These are determined from
information computed by the most recent GLM (generalized linear or
linear model) command such as regress(), anova(), or poisson().

Term is usually a quoted string or CHARACTER variable such as "a.b"
which exactly matches a term in the most recent model, that is, "a.b" is
not the same as "b.a".  An interaction term produces a matrix or array
with the leftmost subscript corresponding to the leftmost factor in
Term.  When a model term contains {expr} where expr is a MacAnova
expression, '{' and '}' are part of the term name and must be included.

For a term which consists of a single factor or variate, Term can be its
unquoted name.

Alternatively, Term can be a integer between 1 and the number of terms,
excluding the final error term.  For example, unless the model contained
"-1", coefs(1) gets the estimated intercept or grand mean.

coefs() (no Term specified) computes coefficients for all terms in the
model as a structure with one component for each term.  The component
names are taken from the term names, truncated if necessary to 12
characters.  When any truncation is necessary, the complete term names
are attached to the result as labels.  See topic 'labels'.

@@@@silent_keyword#Keyword 'silent'
coefs(Term, silent:T) and coefs(silent:T) do the same, but certain
warning and advisory messages are suppressed.  'silent:T' can be used
with any other keywords.  This feature is useful in a macro when warning
messages might confuse the user, or in a simulation.  The default value
of 'silent' is False unless the value of option' 'warnings' is False.

@@@@se_keyword#Keyword 'se'
coefs(Term,se:T) and coefs(se:T) also compute standard errors and are
equivalent to secoefs(Term) and secoefs(), respectively.  You can also
use keywords 'error' and 'byterm' in this case.  See secoefs().

Caution: After anova(), manova() and regress(), standard errors are
computed using the final error mean square in the model.  This may not
be appropriate with mixed models, including split plot designs.

@@@@multivariate_use#Multivariate use
coefs(Term,Varno) or coefs(,Varno) computes coefficients only for
variable number Varno in the case of a multivariate dependent variable.
When present, Varno must be the second argument and any keywords must
follow it.

@@@@limitations#Limitations
coefs() does not work after screen() or after a GLM command with
'coefs:F' as an argument.

@@@@example#Example
Example: After anova("y= a + b + a.b")
   coefs(a), coefs("a"), or coefs(2) will compute the main effect
     coefficients for factor a
   coefs("a.b") or coefs(4) will produce a matrix of the a by b
     interaction coefficients.
   coefs() will produce all coefficients, including the constant.

@@@@see_also#Cross references
See also secoefs(), contrast(), modelinfo(), popmodel(), pushmodel()
@@@@______

====colplot()#plotting
%%%%
colplot(x [, graphics keyword phrases]), x a REAL matrix
%%%%
@@@@usage#Usage
colplot(x) makes an "interaction" plot of the data in the REAL matrix x.
The plotting positions are the row numbers and the values in x.  Points
within each column are joined by lines.  Any keywords useable in
chplot() may follow x.  colplot() is implemented as a pre-defined macro.

When option 'dumbplot' has been set False (see subtopic
'options:"dumbplot"'), the plot will be a low resolution plot unless
'dumb:F' is an argument.

See topic 'graph_keys', 'graph_border' and 'graph_ticks' for information
on other keywords that can be used with colplot().

@@@@example#Example
Example:
  Cmd> colplot(run(20)^(.2*run(5)'),xlab:"X",\
        title:"X^.2, X^.4, X^.6, X^.8, X")

@@@@see_also#Cross references
See also topic rowplot().
@@@@______

====comments#syntax
%%%%
[command1; command2 ...] # comment which will be ignored
%%%%
@@@@usage#Usage
Anything following a '#' on a line is ignored unless it is part of a
string quoted with '"'.  You can use this feature to add comments to
spooled output or usage information to macros.  The '#' and everything
following up to the end of the line or a terminating '\' are skipped.

You can use macrousage() to print any comment lines (lines starting with
"#") in a macro.  It is good practice to include comment lines
describing the usage.  They should not be confused with header lines
starting with ')' in a file which may also give usage information.  See
topics macrousage(), 'macros', 'files'.

@@@@example#Example
Example:
  Cmd> xbar <- sum(x)/nrows(x) # compute mean as a row vector
is just the same as
  Cmd> xbar <- sum(x)/nrows(x)

@@@@see_also#Cross references
See also spool().
@@@@______

====complex#time series,complex arithmetic
%%%%
cmplx(re,im), hprdhj(hx1,hx2), hprdh(hx1,hx2), hdivhj(hx1,hx2),
hdivh(hx1,hx2), cprdc(cx1,cx2), cprdcj(cx1,cx2), cdivc(cx1,cx2),
cdivcj(cx1,cx2), cmatmultc(cx1,cx2), csolve(cx), ceigen(), cdiag(cx),
ctrace(), ctranspose(), hpolar(hx), cpolar(cx), hrect(hx), crect(cx),
hreal(hx), himag(hx), creal(cx), cimag(cx), csubscr()
%%%%
@@@@introduction#Introduction
MacAnova stores complex matrices in two forms, fully complex and packed
Hermitian.

@@@@fully_complex#Fully complex
The fully complex form has alternating columns R1, C1, R2, C2, ...,
containing the real and imaginary parts of the columns of the complex
matrix represented.  When such a matrix has an odd number of columns,
there is an implied additional column of zeros.  Thus columns 1, 3, 5,
... are the real parts of complex series and columns 2, 4, 6, ... are
the corresponding imaginary parts.

@@@@packed_hermitian#Packed hermitian
The packed Hermitian form is meaningful only for matrices whose columns
represent periodic complex frequency functions with Hermitian symmetry
sampled at frequencies 0,1/n,2/m,...,(n-1)/n cycles, where n is the
number of rows.  Hermitian symmetry for such a function g(f) means g(-f)
= g(1-f) = conj(g(f)).  This implies that g(0) and g(.5) are real and
g((n-k)/n) = conj(g(k/n)), and hence only n real numbers are required to
represent such series.

The n numbers are stored in the following order, the packed Hermitian
form:
 z[0],Re(z[1]),...,Re(z[floor((n-1)/2)]),{z[n/2]},Im(floor(z[(n-1)/2])),
     ...,Im(z[1]),
where z[k] = g(k/n).  z[n/2] is omitted when n is odd.

@@@@functions_for_complex_data#Functions for complex data
You can create a fully complex matrix from its real and imaginary parts
Re and Im using cmplx(Re,Im).  cmplx(Re) is equivalent to
cmplx(Re,0*Re), returning a complex matrix with 0 imaginary part.

You can extract the real and imaginary parts and compute the complex
conjugate of a fully complex matrix cx by creal(cx), cimag(cx), and
cconj(cx).

You can do the same for a packed Hermitian matrix hx by hreal(hx),
himag(hx), and hconj(hx).

You can switch between the two representations of a periodic Hermitian
series by htoc(hx) and ctoh(cx).

You can transform both types of complex matrices to and from polar form
(with the modulus being stored as the real part and the argument or
phase as the imaginary part of fully complex or packed hermitian
matrices) by cpolar(cx), crect(cx), hpolar(hx), and hrect(hx).

You can multiply them element by element by cprdc(cx1,cx2), cprdcj(cx1,
cx2), hprdh(hx1,hx2), and hprdhj(hx1,hx2).

You can divide them element by element by cdivc(cx1,cx2), cdivcj(cx1,
cx2), hdivh(hx1,hx2), and hdivhj(hx1,hx2).

@@@@macros_for_complex_matrices#Macros for complex matrices
There are macros for working with complex matrices A and B represented
as real matrices a and b in fully complex form.  These are cmatmultc()
(A %*% B, A %c% B, A %C% B), ctrace() (trace(A)), cdiag() (diag(A)),
csolve() (inverse of A), ctranspose() (A'), cjtranspose() (conj(A)'),
ceigen() (eigenvalues and eigenvectors of a square Hermitian A) and
csubstr() (extract elements as if by subscripts).

@@@@see_also#Cross references
See also subtopic 'matrices:"complex_matrices"', polyroot(), rft(),
hft(), cft().

@@@@______

====compnames()#structures,character variables
%%%%
compnames(S), S a structure
%%%%
@@@@usage#Usage
compnames(struc) returns a CHARACTER vector containing the names of the
components of STRUCTURE struc.

@@@@example#Example
  Cmd>compnames(structure(a:1,b:2,c:17)) # returns vector("a","b","c").
  (1) "a"
  (2) "b"
  (3) "c"

@@@@see_also#Cross references
See also topics structure(), strconcat(), changestr(), 'structures',
nameof(), varnames()
@@@@______

====console()#files,input
%%%%
y <- console()
%%%%
@@@@usage#Usage
y <- console() uses a pre-defined macro to read a vector using variable
CONSOLE as the filename.  This results in a request to type the data in,
terminating it with '!'.  This has the advantage over y <- vector(1.3,
4.5, 6.7, 2.5, ... ), say, in that the commas do not need to be typed.
Variable CONSOLE can be used with any operation that reads or writes a
file.  Its value is ignored.

Command vecread() is used by console() so you can use '?' to specify
missing data.

On a windowed versions, you enter data into a dialog box.  Pressing
Return or clicking on the OK button ends a line.  The Done button
terminates the data.

@@@@echo_keyword#Keyword 'echo'
y <- console(echo:F) suppresses any echoing of lines read.  Such echoing
is the default behavior on windowed versions, or when using console() in
a batch file on any system.

@@@@see_also#Cross references
See vecread().
@@@@______

====contrast()#glm,anova,comparisons
%%%%
contrast(Term,Coefs [,Byvar] [,errorTerm:ErrorTerm] [,silent:T]), Term a
  factor in the most recent GLM model or a character SCALAR or positive
  integer specifying a term and ErrorTerm a CHARACTER scalar or positive
  integer, Coefs REAL, Byvar a factor in the most recent GLM or a
  CHARACTER scalar specifying such a factor
%%%%
@@@@usage#Usage
contrast(Term,Coefs) computes the estimated value, sum of squares, and
standard error for the contrast in the levels of the term specified by
Term.  The term specified must be made up exclusively of factor
variables in the model used by the most recent GLM (generalized linear
or linear model) command such as anova() or poisson().

Term is usually a CHARACTER scalar or quoted string such as "a" or
"b.c".  When the term contains just one factor, you can use just the
unquoted factor name.  Instead of a name, Term can be an integer between
1 and the number of terms in the model, counting CONSTANT if it is in
the model.  For example, after anova("a+b+a.b"), contrast(b,Coefs),
contrast("b",Coefs) and contrast(3,Coefs) are equivalent.

When any of the variables in the model are of the form {expr}, where
expr is a MacAnova expression, you must specify the variable in Term in
the same way or by number.  See topic 'models'.

@@@@result#Result
The result is a structure with components 'estimate', 'ss', and 'se'.
For example, when factor a in a model has 5 levels, contrast("a",
vector(2,2,2,-3,-3)/6) compares the average effect of the first 3 levels
of factor a with the average effect of the last 2.

@@@@multi_factor_case#Multi factor case
When Term contains more than one factor (for example "a.b"), Coefs must
be an array with dimensions matching the number of levels in the factors
of Term.  The contrast coefficients must sum to zero, but MacAnova does
not check to see if the contrast lies in any particular subspace.

You can use outer() to create multidimensional contrast coefficients
that are products of one dimensional contrasts.  For example, if factors
a and b have 2 and 3 levels, respectively, after anova("y = a*b"),

@@@@example#Example
  Cmd> contrast("a.b", outer(vector(1,-1), vector(2,-1,-1)))

compute results for a product contrast that forms part of the a.b sum
of squares.  See outer().

@@@@by_variables#By variables
contrast(Term,Coefs,Byvar) computes the contrast, sum of squares, and
standard error separately for each level of the factor variable (the
"byvariable") given in the CHARACTER or quoted string variable Byvar.

For example, after anova("y=a*b"), where a has three levels,
contrast("a",vector(-1,0,1),b) computes the indicated contrast for each
level of b.  Byvar can be specified by a quoted name but not by a
positive integer.

@@@@errorterm_keyword#Keyword 'errorterm'
contrast(Term, Coefs [,Byvar], errorterm:ErrTerm) does the same except
the mean square error used in computing standard errors comes from the
term specified by ErrTerm.  ErrTerm can either be a positive integer
specifying a term number, or a CHARACTER scalar or quoted string
containing the name of a term in the model ("a.b.c", for example).

@@@@silent_keyword#Keyword 'silent'
contrast(Term, Coefs, [,Byvar] [, errorterm:ErrTerm], silent:T) does the
same, except that certain warning or advisory messages are suppressed.
The default value of 'silent' is False unless the value of option'
'warnings' is False.

@@@@limitations#Limitations
contrast() does not work after screen() or after any GLM command with
'coefs:F' as an argument.

@@@@unbalanced_models#Unbalanced models
For unbalanced models, contrasts are computed as follows.

No byvariable:
  When Term corresponds to a term in the current anova model, the sum of
  squares is that for removal of the contrast degree of freedom from the
  complete model.  It is actually computed as a linear combination of
  the non-aliased coefficients associated with the term.

  When Term is not present in the model, the sum of squares is the
  incremental sum of squares obtained when adding the contrast df to the
  complete model, that is, the contrast is adjusted for all terms in the
  model.

Byvariable specified:
  The contrast is unadjusted for any other terms in the model, that is,
  it is computed as if the contrast degree of freedom at that level of
  the byvariable is the only degree of freedom in the model).

In all three cases, the MSE used in computing the standard error is the
error mean square (or other mean square as specified by 'errorterm')
from the most recent GLM command.

@@@@after_nonlinear_GLM#After nonlinear GLM
After logistic(), probit(), poisson(), and other GLMs fit iteratively by
glmfit() (but not robust()), contrast() computes the estimated value and
the deviance associated with the contrast based on full model weights.
Key word 'byvar' may not be used, but deviances are otherwise computed
as after anova().  Standard errors are computed using a scale parameter
of 1, or the value specified by keyword 'scale' on the GLM command.
Instead of 'ss', the second component of the result has name 'deviance'.

After robust(), the contrast value is computed based on coefficients
from the full model.  The "ss" computed is the square of the ratio of
the estimated contrast to its estimated standard error multiplied by the
error mean square.  Keyword 'byvar' cannot be used.

Contrast() does not work following fastanova(), ipf(), or screen() or
after a GLM command with coefs:F.

@@@@examples#Examples
Example:
  Cmd> anova("y=a+b+a.b")
  Cmd> contrast("b",vector(-1,1,0)) # assumes b has 3 levels
  Cmd> contrast("b",vector(-1,1,0),"a") # a is byvariable
  Cmd> contrast("a.b",matrix(vector(-1,1,0,0,1,-1),2))# assumes 2 by 3

@@@@see_also#Cross references
See also coefs(), secoefs(), modelinfo(), popmodel(), pushmodel()
@@@@______

====convolve()#time series
%%%%
convolve(wts, x [, reverse:T, decimate:M]), wts a REAL vector, x a REAL
  vector or matrix, M a positive integer
%%%%
@@@@usage#Usage
convolve(a,x) performs a circular convolution of the values in vector a
with each of the columns of vector or matrix x.  If we index rows
starting with 0, so that a contains elements a[0], a[1], ..., a[p-1],
and a column of x contains x[0], x[1], ..., x[n-1], the corresponding
column of the result is computed as follows:

  d[k] = sum(a[j]*x[k-j],j=0,min(k,p-1)) + sum(a[j]*x[k-j+n],j=k+1,p-1),

where the second sum is omitted when k >= p - 1.

@@@@reverse_keyword#Keyword 'reverse'
convolve(a,x,reverse:T) computes sums of circularly lagged products of
the elements of a and each column of x.  Explicitly, with the same
indexing,

 d[k] = sum(a[j]*x[j-k+n],j=0,min(k-1,p-1)) + sum(a[j]*x[j-k],j=k,p-1)

where the first sum is omitted when k = 0 and the second sum is
omitted when k >= p.

@@@@decimate_keyword#Keyword 'decimate'
convolve(a,x,decimate:M) and convolve(a,x,reverse:T,decimate:M) "thin"
the result by a factor of about 1/M.  M must be a positive integer.

Specifically, if d is the result of an unthinned convolution, the value
returned is a K by ncols(x) matrix where K = floor((nrows(x)-1)/M) + 1
with d[1 + (j-1)*M,] in row j.  This option is useful if a is the
impulse response function of a smoothing filter.

@@@@see_also#Cross references
See also autoreg(), movavg().
@@@@______

====copyright%#general
%%%%
Copyright (C) 1994 - 2005 by Gary W. Oehlert and Christopher Bingham.
Type help(copyright) for fuller information and acknowledgments.
%%%%
@@@@authors#Authors
MacAnova is conceived and programmed by Gary W. Oehlert and Christopher
Bingham, School of Statistics, University of Minnesota, and is Copyright
(C) 1994 - 2001 by them. Their e-mail addresses are kb@stat.umn.edu and
gary@stat.umn.edu.

@@@@gnu_public_license#GNU public license
MacAnova is distributed under the terms of the GNU Public License,
Version 2 (see file COPYING distributed with MacAnova).

There is no warranty of any kind for MacAnova, either expressed or
implied.  MacAnova is distributed "as is".  See file Copyint.txt for a
more complete statement.

@@@@home_page#Home page
The MacAnova WWW home page is
  http://www.stat.umn.edu/macanova
Executable versions of MacAnova are available there, along with source
and PDF versions of the User's Guide and other documentation.  An
up-to-date mirror of these files is maintained by statlib at
  http://lib.stat.cmu.edu/

Reports of bugs should be emailed to kb@stat.umn.edu.

@@@@software_used#Software used
The Carapace versions of MacAnova (Windows, Mac OS X, GTK Linux)
make use of the wxWidgets cross-platform library available at
http://www.wxwidgets.org.  The wxWidgets license is very similar to
the LGPL.  Carapace is using wxWidgets versions 2.4.2 (Windows and
GTK) and 2.5.3 (Mac OS X); we plan to move to 2.6 when is becomes
available.

The extended memory MSDOS version (DJ) is compiled using a version of
Gnu gcc developed and copyrighted by D. J. Delorie (DJGPP) and
distributed under the terms of the GNU Public License.  Source and
executable for DJGPP can be found at http://www.delorie.com/djgpp

The Mac OS 9 (classic) version uses TransSkel 3.12, a transportable
Macintosh application skeleton placed in the public domain by Paul
Dubois (dubois@primate.wisc.edu).

Plotting is done using a modification of GNUplot, Copyright (C) 1986,
1987 Thomas Williams, Colin Kelley.

The Unix/Linux version and the extended memory DOS version (DJGPP) allow
command line editing and history maintenance using the GNU Readline
Library, Copyright (C) 1988, 1991 Free Software Foundation, Inc.,
distributed under the terms of the GNU public license.  A compressed tar
archive of version 2.0 (used in the Unix/Linux version) is available
through the MacAnova home page.  The version used in the DOS DJGPP
version was included with the source for gdb4.12 found on
ftp://oak.oakland.edu/ which has been reorganized since we retrieved it.

@@@@fortran_programs_used#Fortran programs used
Included in MacAnova's distribution are modified translations from
Fortran to C of the following programs written by others.

  Program screen and related subroutines for computing regressions by
  leaps and bounds by G.M.Furnival and R.W.Wilson supplied by Sanford
  Weisberg.  See their paper, Regression by Leaps and Bounds, Techno-
  metrics 16 (1974) 499-511.

  Subroutines rebak, reduc, rsg, tql2, tqlrat, tred1, tred2, svd,
  tridib, and tinvit from the Eispack library.

  Subroutines dchdc, dgeco, dgedi, dgefa, dgesl, and dqrdc from the
  Linpack library.

  Subroutines for computing mixed radix fast Fourier transforms written
  by Gordon Sande at the University of Chicago circa 1968.

  Program hc and related subroutines for computing hierarchical cluster
  analysis by F. Murtagh, retrieved from statlib.

  Subroutines for making stem and leaf displays from the book ABCs of
  EDA by David Hoaglin and Paul Velleman, Duxbury 1981.

  Subroutines to compute the roots of real polynomials from Algorithm
  493 published in TOMS retrieved from netlib.

  Code to compute the cumulative normal adapted from W. J. Kennedy and
  J. E. Gentle, Statistical Computing, Marcel Dekker, 1980, pp 90-92,
  which is based on W. J. Cody, Rational Chebyshev approximations for
  the error function, Math. Comp 23 (1969) 631-637.

  Code to compute the inverse of a normal distribution from Algorithm AS
  111 by J.D. Beasley and S. G. Springer, Appl. Statist. 26 (1977),
  118-121 retrieved from statlib.

  Code to compute the inverse Student's t-distribution from CACM
  Algorithm 396, by G. W. Hill retrieved from netlib.

  Code to compute the (central) Beta distribution from a subroutine of
  W.  Fullerton, Los Alamos, based on Bosten and Battiste, Remark on
  Algorithm 179, CACM 17 (1974) p. 153

  Code to compute the inverse Beta distribution from Algorithm AS 109 by
  G.  W. Cran, K. J. Martin and G. E. Thomas, Appl. Statist. 26 (1977),
  111-114 retrieved from statlib.

  Code to compute the non-central Beta distribution from Algorithm AS
  226 by R. V. Lenth, Appl. Statist. 36 (1987) 241-244, incorporating
  changes by H. Frick, Appl. Statist. 39 (1990) 311-12, retrieved from
  statlib

  Code to compute the gamma and chi-squared cumulative distributions
  from Algorithm AS 91 by D. J. Best and D. E. Roberts,
  Appl. Statist. 24 (1975), 385-388, incorporating revisions by
  B. L. Shea, Appl. Statist. 40 (1991), 233-235), retrieved from
  statlib.

  Code to compute the non-central chi-squared cumulative distribution
  from Algorithm AS 275 by Cherng G. Ding, Appl. Statist. 24 (1992),
  478-482, retrieved from statlib.

  Code to compute the non-central Student's t cumulative distribution
  from Algorithm AS 243 by Russell V. Lenth,  Appl. Statist. 38 (1989),
  185-189, retrieved from statlib.

  Code to compute the cumulative distribution function and its inverse
  for the Studentized range from Algorithm AS 190 by R. E. Lund and
  J. R. Lund, Appl. Statist. 32 (1983) 204-210, incorporating
  corrections by Lund and Lund, Appl. Statist. 34 (1985) 104 and
  I. D. Hill, Appl. Statist. 36 (1987) 119, retrieved from statlib.

  Code for a combined uniform pseudo-random number generator for 32 bit
  machines in P. L'Ecuyer 1988 Comm. ACM, retrieved from netlib.

  Code implementing the Singleton quicksort algorithm (Comm. ACM
  Algorithm 347) adapted from ssort.f in cmlib.

  Code computing the cumulative distribution for Dunnett's t was adapted
  from Algorithm AS 251 by C. W. Dunnett, Appl. Statist. 38 (1989)
  564-579 incorporating a correction by C. W. Dunnett, Appl. Statist. 42
  (1993) p. 709, and subroutine mvstud, also by Dunnett, that is part of
  the AS 251 distribution from statlib.

  Code generating a pseudo-random Poisson variable adapted from a
  Fortran program in C. D. Kemp and W. A. Kemp, Poisson random
  variate generation, Appl. Statist. 40 (1991) 143-158.

  Code generating a pseudo-random binomial variable adapted from
  Algorithm 678, Transactions on Math. Software 15, 394-397 by Voratas
  Kachitvichyanukul and Bruce Schmeiser.

  Code implementing varimax rotation from subroutine varmx supplied by
  Douglas Hawkins (doug@stat.umn.edu).

  Code implementing k-means clustering from subroutine trwcla supplied
  by Douglas Hawkins (doug@stat.umn.edu).

  Code used to compute inverses to cumulative distributions from
  subroutine fsolve supplied by Douglas Hawkins (doug@stat.umn.edu).  It
  is used by invchi() to compute the inverse of non-central chi-squared
  and by invdunnett() to compute probability points of Dunnett's t.

@@@@macros_from_fortran#Macros from fortran
Certain macros are also based on Fortran code:
  Macro levmar() in file Arima.mac is based on a Fortran program of Ken
  Brown.  See Brown,K.,M. and Dennis,J.,E., Derivative free analogues of
  the Levenberg-Marquardt and Gauss algorithms for nonlinear least
  squares approximation.  Numerische Mathematik, Vol. 18, pp. 289-297
  (1972)

  Macro neldermead() in file Math.mac is based on Fortran subroutine
  MINIM by D. E. Shaw, CSIRO, Division of Mathematics & Statistics, with
  amendments by R. W. M. Wedderburn, Rothamsted Experimental Station,
  and Alan Miller, CSIRO, Division of Mathematics & Statistics.  See
  also Nelder & Mead, The Computer Journal 7 (1965), 308-313.  MINIM was
  retrieved from statlib.

  Macro contourplot() and associated macros contour(), _Follow() and
  findcontour() are based on Fortran routines by Dan LaLiberte,
  implementing methods in Crane, C.M.(1972), Contour plotting algorithm,
  'The Computer Journal', Vol. 15, pp. 382-384 and Cottafava, G., Andle
  Moli, G. (1969). Automatic Contour Map, 'Comm. ACM', Vol. 12,
  pp. 386-391.

====cor()#descriptive statistics
%%%%
cor(x1 [,x2,...]), x1, x2, ... REAL vectors or matrices all with the
  same number of rows
%%%%
@@@@usage#Usage
cor(x) computes a correlation matrix for data in REAL matrix x.  Any row
of x that contains missing data is entirely omitted.  It is an error to
have missing data in all rows.

cor(a,b,c,... ), where a, b, c, ... are vectors or matrices with the
same number of rows, is equivalent to cor(hconcat(a,b,c,...)) .  See
hconcat().

When any column in the input is constant (all values the same), the
entire corresponding row and column of the output is set MISSING,
including the diagonal, and a warning message is printed.  In particular
this occurs when the number of rows in the input is 1.

Non-MISSING elements of the diagonal are exactly 1.
@@@@______

====cos()#transformations
%%%%
cos(x [, degrees:T or radians:T or cycles:T]), x REAL or a structure
  with REAL components x in radians (default), cycles, or degrees as set
  by option "angles" or the optional keyword
%%%%
@@@@usage#Usage
cos(x) computes the cosine of the values of the elements of x,
where x is a REAL scalar, vector, matrix or array.  The result has the
same shape as x.

@@@@units#Units
The argument is considered to be in units of radians, degrees or cycles
as determined by the value of option 'angles'.  The default is radians.
See topic 'options'.

cos(x, radians:T), cos(x, degrees:T), cos(x, cycles:T) interpret x as in
the indicated units, regardless of the value of option 'angles'.

@@@@missing_or_too_large_argument#Missing or too large argument
When any element of x is MISSING or is too large (> 5000000*PI radians
in absolute value), the corresponding element of the result is MISSING
and a warning message is printed.

@@@@structure_argument#Structure argument
When x is a structure, all of whose non-structure components are REAL,
cos(x [,UNITS:T]), where UNITS is one of 'radians', 'degrees' or
'cycles', is a structure of the same shape and with the same component
names as x with each non-structure component transformed by cos().

@@@@see_also#Cross references
See topic 'transformations' for more information on cos(), including its
use with a CHARACTER argument.
@@@@______

====cosh()#transformations
%%%%
@@@@usage#Usage
cosh(x) returns the hyperbolic cosine of the elements of x, when x is a
REAL scalar, vector, matrix or array.  The result has the same shape as
x.  In terms of other functions, cosh(x) = (exp(x) + exp(-x))/2.

@@@@missing_or_too_large_argument#Missing or too large argument
When any element of x is MISSING or > 710.4758600739439 in absolute
value, the corresponding element of cosh(x) is MISSING and a warning
message is printed.

@@@@structure_argument#Structure argument
When x is a structure, all of whose non-structure components are REAL,
cosh(x) is a structure of the same shape and with the same component
names as x, with each non-structure component transformed by cosh().

@@@@see_also#Cross references
See topic 'transformations' for more information on cosh().
@@@@______

%%%%
See topic 'transformations' for information on cosh().

====cpolar()#time series,complex arithmetic
%%%%
cpolar(hx [,unwind:F or crit:val]), hx a REAL matrix representing
  complex data, val a REAL scalar, 0.5 < val <= 1
%%%%
@@@@usage#Usage
cpolar(cx) computes the polar form of the fully complex matrix cx,
storing it in pseudo fully complex form, with the amplitude or absolute
value as the real part and the phase as imaginary part.  Thus
creal(cpolar(cx)) and cimag(cpolar(cx)) return REAL matrices whose
columns are the amplitudes and phases of the complex series represented
by pairs of columns of cx.

@@@@angle_units#Angle units
The value of the computed phase is in radians, degrees or cycles
depending on the value of option 'angles'.  See subtopic
'options:"angles"'.  By default the phase is "unwound" so as to minimize
discontinuities arising from wrap-around.

@@@@crit_and_unwind_keywords#Keywords 'crit' and 'unwind'
cpolar(cx,crit:Val), where .5 <= Val < 1 changes the criterion
controlling "unwinding".  The default is .75.  See unwind() for details.

cpolar(cx,unwind:F) suppresses the unwinding.

@@@@see_also#Cross references
See also hpolar(), crect(), hrect().

See topic 'complex' for discussion of complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====cprdc()#time series,complex arithmetic
%%%%
cprdc(cx1 [, cx2]), cx1 and cx2 REAL matrices representing complex data
%%%%
@@@@usage#Usage
cprdc(cx1, cx2) computes the element wise complex multiplication of
fully complex (pairs of columns constitute real and imaginary parts)
matrices cx1 and cx2.  When cx1 or cx2 has an odd number of columns, it
is augmented with a column of zeros before multiplication.

cprdc(cx) is equivalent to cprdc(cx,cx).

When cx1 or cx2 represents a complex scalar (nrows(cx1) = 1 and
ncols(cx1) <= 2 or nrows(cx2) = 1 and ncols(cx2) <= 2), cprdc()
multiplies every element of the other argument by that scalar.  For
example,

  Cmd> i_times_cx <- cprdc(vector(0,1)',cx)

multiplies cx by i = sqrt(-1).

When nrows(cx1) = 1 or nrows(cx2) = 1, cprdc() multiplies each row in
the other argument by that single row.

When cx1 or cx2 represents a single complex series (ncols(cx1) <= 2 or
ncols(cx2) <= 2), cprdc() multiplies each series in the other argument
by that series.

It is an error when both nrows(cx1) > 1 and nrows(cx2) > 1 and
nrows(cx1) != nrows(cx2), or when both ncols(cx1) > 2 and ncols(cx2) > 2
and ceiling(ncols(cx1)/2) != ceiling(ncols(cx2)/2) (the number of
complex series represented differs).

@@@@examples#Examples
Examples:
  When ncols(cx1) = 2 and ncols(cx2) = 5, cprdc(cx1,cx2) is equivalent to
  cprdc(hconcat(cx1,cx1,cx1),hconcat(cx2,rep(0,nrows(cx2))))

  When a and b are REAL scalars, cprdc(cmplx(a,b),cx) computes the
  complex scalar product of a + b*i and cx.

@@@@see_also#Cross references
See also cprdcj(), hprdh(), hprdhj(), cdivc(), cdivcj(), hdivh(),
hdivhj(), hconcat(), rep(), nrows(), ncols().

See topic 'complex' for discussion of complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====cprdcj()#time series,complex arithmetic
%%%%
cprdcj(cx1 [, cx2]), cx1 and cx2 REAL matrices representing complex data
%%%%
@@@@usage#Usage
cprdcj(cx1, cx2) computes the element wise complex multiplication of
fully complex (pairs of columns constitute real and imaginary parts)
matrices cx1 and cconj(cx2).  When cx1 or cx2 has an odd number of
columns, it is augmented with a column of zeros before multiplication.

cprdcj(cx) is equivalent to cprdcj(cx,cx) and returns as output a matrix
with the squared moduli of the elements of cx, considered as complex
numbers, in the odd columns (real part) of the result, with zero's in
the even columns (imaginary part).

When cx1 or cx2 represents a complex scalar (nrows(cx1) = 1 and
ncols(cx1) <= 2 or nrows(cx2) = 1 and ncols(cx2) <= 2), cprdcj()
multiplies every element of the other argument by that scalar.  For
example,

  Cmd> i_times_cx <- cprdcj(vector(0,1)',cx)

multiplies cconj(cx) by i = sqrt(-1).

When nrows(cx1) = 1 or nrows(cx2) = 1, cprdcj() multiplies each row in
the other argument by that single row.

When cx1 or cx2 represents a single complex series (ncols(cx1) <= 2 or
ncols(cx2) <= 2), cprdcj() multiplies each series in the other argument
by that series.

It is an error when both nrows(cx1) > 1 and nrows(cx2) > 1 and
nrows(cx1) != nrows(cx2), or when both ncols(cx1) > 2 and ncols(cx2) > 2
and ceiling(ncols(cx1)/2) != ceiling(ncols(cx2)/2) (the number of
complex series represented differs).

@@@@examples#Examples
Examples:
  When ncols(cx1) = 2 and ncols(cx2) = 5, cprdcj(cx1,cx2) is equivalent
  to cprdcj(hconcat(cx1,cx1,cx1),hconcat(cx2,rep(0,nrows(cx2))))

  When a and b are scalars, cprdcj(cmplx(a,b),cx) computes the complex
  scalar product of a + b*i and cconj(cx).

@@@@see_also#Cross references
See also cprdc(), hprdh(), hprdhj(), cdivc(), cdivcj(), hdivh(),
hdivhj(), cconj(), hconcat(), rep(), nrows(), ncols().

See topic 'complex' for discussion of complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====creal()#complex arithmetic,time series
%%%%
creal(cx), cx a REAL matrix representing complex data
%%%%
@@@@usage#Usage
creal(cx) computes the real part of the fully complex matrix cx.  For
example, creal(matrix(run(10),5)) is vector(1,2,3,4,5).

When cx has an odd number, say 2*m-1, of columns, the last column is
interpreted as the real part of a complex series with zero imaginary
part and the result has m columns.

@@@@see_also#Cross references
See also hconj(), cconj(), hreal(), himag(), cimag().

See topic 'complex' for discussion of complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====crect()#time series,complex arithmetic
%%%%
crect(cx), cx a REAL matrix representing complex data
%%%%
@@@@usage#Usage
crect(cx) is the inverse operation to cpolar().  Matrix cx is assumed to
represent the polar form of a fully complex series, with amplitudes or
absolute values in the real part and phases in the imaginary part.  The
result contains the real and imaginary parts of that series in fully
complex form.  See topic 'complex' for discussion of complex matrices in
MacAnova.

@@@@angle_units#Angle units
The phases are assumed to be in units of radians, degrees or cycles
depending on the value of option 'angles'.  See subtopic
'options:"angles"'.

@@@@see_also#Cross references
See also cpolar(), hpolar(), hrect().
@@@@______

====ctoh()#time series,complex arithmetic
%%%%
ctoh(cx), cx a REAL matrix representing complex data
%%%%
@@@@usage#Usage
ctoh(cx) returns the packed Hermitian symmetrized form of the REAL
matrix cx, considering its columns in pairs as representing unrestricted
Complex series.  When cx is m by 2*n-1, or m by 2*n, ctoh(cx) is m by n,
with column i containing the Hermitian symmetrized form of columns 2*i-1
and 2*i.  When ncols(cx) is odd, the final complex series is assumed to
have imaginary part zero.

When cx actually has Hermitian symmetry, ctoh(cx) represents the same
matrix in packed form.  When cx does not have such symmetry, ctoh(cx)
represents the symmetrized matrix obtained by averaging elements that
should be equal and discarding the imaginary parts of elements that
should be real.

@@@@see_also#Cross references
See topic 'complex' for discussion of complex matrices in MacAnova.

See also htoc(), cconj(), hconj(), hreal(), himag(), creal(), cimag().

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====cumbeta()#probabilities
%%%%
cumbeta (x,alpha,beta[,lam] [,upper:T or lower:F]), x, alpha, beta, and
  lam REAL, elements of alpha, beta > 0, lam >= 0
%%%%
@@@@usage#Usage
cumbeta(Val,a,b) computes the probabilities that a beta random variable
with parameters a and b would be <= the elements of the vector,
matrix, or array Val.

cumbeta(Val,a,b,lam) computes similar probabilities for non-central beta
with noncentrality parameter lam.

Any of Val, a, b, or lam that are not scalars (single numbers) must be
vectors, matrices, or arrays with the same size and shape which will
also be the size and shape of the result.

cumbeta(Val,a,b [,lam] ,upper:T) and cumbeta(Val,a,b [,lam] ,lower:F) do
the same, except P(beta >= Val) is computed.

The elements of a, b and lam must be positive REAL numbers.

@@@@example#Example
Example:
  Cmd> cumbeta(.173,1.5,2.5,upper:T) # upper tail prob,a = 1.5,b = 2.5
  (1)      0.79252

  Cmd> 1 - cumbeta(.173,1.5,2.5) # same
  (1)      0.79252

@@@@see_also#Cross references
See also cumF(), invF(), invbeta().
@@@@______

====cumbin()#probabilities
%%%%
cumbin(x,N,P [,upper:T or lower:F]), x, N and P REAL, elements of N
  integers > 0, elements of P between 0 and 1
%%%%
@@@@usage#Usage
cumbin(Val,N,P) computes the probabilities that a binomial random
variable with N trials at probability P would be <= elements of the
vector, matrix or array Val.  When Val is not integral, the result is
the same as cumbin(floor(Val),N,P).

Any of Val, N, and P that are not scalars (single numbers) must be
vectors, matrices, or arrays with the same size and shape which will
also be the size and shape of the result.

The elements of N must be positive integers less than 100,000 and the
elements of P must be between zero and one.

cumbin(Val,N,P,upper:T) and cumbin(Val,N,P,lower:F) compute the
probability that the binomial random variable is >= elements of Val.
This is mathematically the same as 1 - cumbin(ceiling(Val - 1),N,P), not
1 - cumbin(Val,N,P)

Note that when Val is an integer, P(x = Val) is included in both
cumbin(Val,N,P) and cumbin(Val,N,P,upper:T).

@@@@computing_pvalues#Computing P values
If x_obs is an observed number of successes in a sequence of n
independent trials with constant p = P(success), you can use cumbin() to
compute P-values for a test of H_0: p = p_0 as follows:
    H_a      P-value
  p > p_0    cumbin(x_obs,n,p_0,upper:T)
  p < p_0    cumbin(x_obs,n,p_0)
  p != p_0   2*min(cumbin(x_obs,n,p_0),cumbin(x_obs,n,p_0,upper:T))

@@@@example#Example
Example:
  Cmd> 1 - cumbin(7,13,.25) # P(x > 7) with n = 13, p = .25
  (1)   0.0056493

  Cmd> cumbin(8,13,.25,upper:T) # or cumbin(8,13,.25,lower:F), same
  (1)   0.0056493

@@@@see_also#Cross references
See also cumpoi().  See invbeta:"binomical_confidence_interval" for
information on computing a confidence interval for p based on a binomial
random variable
@@@@______

====cumchi()#probabilities
%%%%
cumchi(x,df [,upper:T or lower:F]), x and df REAL, elements of df > 0
cumchi(x,df,lam [,upper:T or lower:F]), same x, df, lam REAL with 0 <=
  lam[i] < 1419.56542578676
%%%%
@@@@usage#Usage
cumchi(Val,df) computes P(x <= Val) where x is a chi-square random
variable with df degrees of freedom.  When Val is a vector, matrix or
array, the probabilities are computed for each element.  When Val and df
are both not scalars, they must be the same size and shape which will
also be the size and shape of the result.

The elements of df must be positive (fractional degrees of freedom are
allowed).

cumchi(Val, df, upper:T) and cumchi(Val, df, lower:F) do the same except
the upper tail probability P(x >= Val) is computed.  It is
mathematically the same as 1 - cumchi(Val, df), although a more accurate
value may be computed.

@@@@example_1#Example
  Cmd> 1 - cumchi(sum((obs-e)^2/e), nrows(obs) - 1) # P value

  Cmd> cumchi(sum((obs-e)^2/e), nrows(obs) - 1, upper:T) # same
@@@@______

@@@@non_central_chi_squared#Non central chi squared
cumchi(Val,df,lam) computes P(x <= Val) where x is a non-central
chi-square random variable with df degrees of freedom and non-centrality
parameter lam.  Both cumchi(Val,df,lam,upper:T) and cumchi(Val,df,lam,
lower:F) compute P(X >= Val).  All non-scalar arguments must be the same
size and shape which will also be the size and shape of the result.  The
elements of Val must be non-negative and less than 1419.56542578676.

@@@@example_2#Example
Power of 5% Chi-squared test of test of H_0: p[1] = p0[1], ..., p[k] =
p0[k] when p[j] = p1[j], j = 1,...,k based on a multinomial sample of
size n:
  Cmd> cumchi(invchi(.05,k-1,upper:T),k-1,n*sum((p1-p0)^2/p0),upper:T)

@@@@see_also#Cross references
See also cumgamma(), invchi(), invgamma().
@@@@______

====cumdunnett()#probabilities,comparisons
%%%%
cumdunnett(x, ngroup, errorDf [,groupSizes][,onesided:T][,epsilon:eps]
  [,upper:T or lower:F]) x REAL, elements of ngroup integers >= 2,
  elements of errorDf >= 1, elements of groupsizes >= 0, eps > 0,
  default = .00001.
%%%%
@@@@usage#Usage
cumdunnett(x, K, Df) computes the probability that Tmax <= x, Tmax =
max(abs(t21), abs(t31), ..., abs(tK1)), where t21, t31, ..., tK1 are K-1
t-statistics of the form tI1 = (xbarI-xbar1)/ stderr(xbarI-xbar1), I =
2,...,K.  xbar1, xbar2, ..., xbarK are the means of independent normal
random samples of the same size with identical population means and
variances, and the standard errors are computed using an independent
estimate of error variance with Df degrees of freedom.  The value is 0
for any x <= 0.  For x >= 0, when K = 2 the value is the same as
2*cumstu(x,Df) - 1.  See cumstu().

cumdunnett(x, K, Df, upper:T) and cumdunnett(x, K, Df, lower:F) do the
same, except they compute the upper tail probability P(Tmax >= x).

@@@@onesided_keyword#Keyword 'onesided'
cumdunnett(x, K, Df, onesided:T) computes the probability that Tmax<=x,
where Tmax is now the maximum of t21, t31, ..., tK1, not of their
absolute values.  When K = 2 the value is the same as cumstu(x,Df).
With 'upper:T' or 'lower:F' it computes the upper tail probability
P(Tmax >= x).
@@@@______

See below for computing probabilities when the sample sizes differ.

x, K and Df must be REAL.  The elements of K must be integers >= 2, and
the elements of Df must be >= 1, not necessarily integers.

Any of the arguments x, K or Df that are not scalars must all be
vectors, matrices or arrays of the same size and shape; the value has
the same size and shape.

@@@@epsilon_keyword#Keyword 'epsilon'
cumdunnett(x, K, Df [, onesided:T] [, upper:T or lower:F], epsilon:eps),
where eps is a small positive number (default .00001) which controls the
accuracy to which the probability is computed; the computed probability
should be no farther than eps from the true probability.

@@@@multiple_comparisons#Multiple comparisons
cumdunnett() is primarily used to compute P values for a multiple
comparisons procedure due to C. W. Dunnett wherein a control group
(group 1) is compared to K-1 other treatment groups using K-1 t-tests.

For a completely randomized design with k treatment groups of size n,
the P value is computed as cumdunnett(maxt, k, k*n - k, upper:T
[,onesided:T]).  See invdunnett() for computing critical values of the
Dunnett test.
@@@@______

Caution: cumdunnett() is very computation intensive and may be
unacceptably slow on an older computer.  On one Macintosh 68000 computer
with no math coprocessor, a single value took about 7 minutes to
compute.

@@@@examples_1#Example
  Cmd> cumdunnett(3.27, 5, 5*8 - 5, upper:T) # P(Tmax >= 3.27)
  (1)     0.00866

computes P(Tmax > 3.27) for a completely randomized design with 5
groups, all with sample size 8.

@@@@differing_sample_sizes#Differing sample sizes
cumdunnett(x, K, Df, groupSizes [,onesided:T, epsilon:eps, upper:T or
lower:F]) computes probabilities for Tmax, with REAL argument groupSizes
specifying the sample sizes.

In the simplest usage, groupSizes is a vector (ndims(groupSizes) = 1),
with elements >= 0.  When groupSizes is a matrix or array
(ndims(groupSizes) > 1), it is treated as if it were a vector, matrix or
array, with one less dimension, each of whose elements is a vector with
length = last dimension of groupSizes.

The first ndims(groupSizes) - 1 dimensions of groupSizes must match the
dimensions of any of x, K, or DF which is not a scalar.  In particular,
a m by 1 matrix, which is treated as a vector of length m by most
MacAnova functions, is interpreted by cumdunnett() as a set of m vectors
of length 1.

In computing an element of the result based on a vector of group sizes
(either all of groupSizes when it is a vector, or a row or "slice" of
groupSizes when ndims(groupSizes) > 1), cumdunnett() uses up to k of the
non-zero leading values in the vector, where k is the corresponding
element of K.  When there are fewer than k non-zero values, the last one
is replicated as many times as needed.  It is an error to have a zero
value followed by a nonzero value or to have all values zero.

When there is only 1 non-zero value in a row or "slice" of groupSize,
the replication of this element means the group sizes are assumed to be
equal.  In particular, this is the interpretation when groupSizes is a
scalar or a m by 1 matrix.

@@@@examples_2#Examples
  Cmd> cumdunnett(3.27, 4, 12 - 4, vector(6,2,2,2), upper:T)
  (1)     0.03070

computes P(Tmax >= 3.27) for a completely randomized design with 4
groups and sample sizes 6, 2, 2 and 2.

  Cmd> cumdunnett(3.27, vector(3,4), vector(12 - 3, 12 - 4),\
       matrix(vector(6,3,3,0, 6,2,2,2),4)', upper:T)
  (1)     0.01825     0.03070

computes P(Tmax >= 3.27) for two completely randomized designs, one with
3 groups and sample sizes 6, 3, and 3, the other with 4 groups with
sample sizes 6, 2, 2, and 2.  Because trailing values in the rows of
groupSizes are replicated, matrix(vector(6,3, 6,2),2)' would be an
equivalent way to specify the group sizes.

  Cmd> cumdunnett(3.27, 4, 12 - 4, 3)
  (1)     0.97182

computes the same result as cumdunnett(3.27, 4, 12 - 4), because
groupSizes is a scalar.

@@@@ratios_of_samples_sizes_used#Ratios of samples sizes used
Only the ratios of non-zero elements of groupSizes are relevant.

For example, for 5 groups (K=5), the following groupSizes are
equivalent: vector(1,2,3,3,3), vector(1,2,3), vector(1,2,3,0,0),
vector(2,4,6).

vector(1,2,3,0,3) and vector(1,2,3,0,0,1) would be errors because a
non-zero value follows a zero.

@@@@caution
Caution: cumdunnett() is somewhat computation intensive.  On a slow
computer you may have to wait several seconds for a result.  Using a
somewhat larger value for epsilon, for example, epsilon:.0001, may speed
up the calculation at the cost of loss of accuracy.

@@@@see_also#Cross references
See also invdunnett(), cumstudrng().
@@@@______

====cumF()#probabilities
%%%%
cumF(x,df1,df2 [,lam] [,upper:T or lower:F]), x, df1, df2 and lam REAL,
  elements of df1 and df2 >i 0 and lam >= 0
%%%%
@@@@usage#Usage
cumF(Val,df1,df2) computes the probabilities that an F random variable
with df1 and df2 degrees of freedom would be less than the elements of
the vector, matrix, or array Val.

cumF(Val,df1,df2,upper:T) and cumF(Val,df1,df2,lower:F) compute upper
tail probabilities.  For large Val, the result may preserve significant
digits that are lost when computing the upper tail probability by 1 -
cumF(Val,df1,df2).

@@@@non_central_F#Non central F
cumF(Val,df1,df2,lam [,upper:T or lower:F]) computes similar
probabilities for non-central F with noncentrality parameter lam.

Any of Val, df1, df2, or lam that are not scalars (single numbers) must
be vectors, matrices, or arrays with the same size and shape which will
also be the size and shape of the result.
@@@@______

The degrees of freedom must be positive REAL numbers (not necessarily
integers).  Upper tail areas of F can be computed as 1 - cumF().

@@@@example#Example
Examples:
Compute P-value for F-statistic following anova():
  Cmd> cumF((SS[2]/DF[2])/(SS[5]/DF[5]), DF[2], DF[5], upper:T)

Compute 2-tail P-value for test of sigma_1 = sigma_2 based on sample
standard deviations s1 and s2 from independent normal samples.

  Cmd> 2*min(cumF(s1^2/s2^2, n1-1, n2-1), \
           cumF(s1^2/s2^2, n1-1, n2-1, upper:T)) # two tail P-value

@@@@see_also#Cross references
See also invF(), cumbeta(), invbeta().
@@@@______

====cumgamma()#probabilities
%%%%
cumgamma(x,alpha [,upper:T or lower:F]), x and alpha REAL, elements of
  alpha > 0
%%%%
@@@@usage#Usage
cumgamma(Val,alpha) computes the probabilities that a gamma random
variable with shape parameter alpha would be less than the elements of
the vector, matrix, or array Val.

When Val and alpha are both not scalars, they must be vectors, matrices,
or arrays with the same size and shape which will also be the size and
shape of the result.

The elements of alpha must be positive.

cumgamma(Val,alpha,upper:T) and cumgamma(Val,alpha,lower:F) compute
upper tail probabilities.  For large Val, this may provide more
significant digits than the mathematically equivalent 1 -
cumgamma(Val,alpha).

cumchi(x,df [,upper:T or lower:F]) is equivalent to cumgamma(x/2,df/2
[,upper:T or lower:F]).

@@@@example#Example
Example:
  Cmd> 1 - cumgamma(13.27, 15.5) # P(x >= 13.27)
  (1)      0.69507

  Cmd> cumgamma(13.27, 15.5, upper:T) # the same
  (1)      0.69507

@@@@see_also#Cross references
See also invgamma(), cumchi(), invchi().
@@@@______

====cumnor()#probabilities
%%%%
cumnor(x [,upper:T or lower:F]), x REAL
%%%%
@@@@usage#Usage
cumnor(Z) computes the probabilities that a standard normal (mean 0,
variance 1) random variable would be less than the elements of the
vector, matrix, or array Z.  The size and shape of the result is the
same as that of Z.

cumnor(Z, upper:T) and cumnor(Z, lower:F) compute upper tail
probabilities.  For large positive Z, these may preserve significant
digits lost by the mathematically equivalent 1 - cumnor(Z).

Two-tailed P values associated with an observed value of z, may be
computed as 2*cumnor(abs(z),upper:T) or 2*(1 - cumnor(abs(z))).

@@@@example#Example
Example:
Two-tail normal P-value for z_obs = 1.841
  Cmd> 2*cumnor(1.841,upper:T) # or 2*(1 - cumnor(1.841))
  (1)     0.06562

@@@@see_also#Cross references
See also invnor().
@@@@______

====cumpoi()#probabilities
%%%%
cumpoi(x,mu [,upper:T or lower:F]), x and mu REAL, elements of mu > 0
%%%%
@@@@usage#Usage
cumpoi(Val,mu) computes the probability that a Poisson random variable
with mean mu is <= the elements of the vector, matrix or array Val.
When Val is not integral, the result is the same as cumpoi(floor(Val),
mu).

When Val and mu are both not scalars, they must be the same size and
shape which will also be the size and shape of the result.

All elements of mu must be non-negative

cumpoi(Val,mu,upper:T) and cumpoi(Val,mu,lower:F) compute the
probability that the Poisson random variable is >= elements of Val.
This is mathematically the same as 1-cumpoi(ceiling(Val-1),mu), not
1-cumpoi(Val,mu).

Note that when Val is an integer, P(x = Val) is included in both
cumpoi(Val,mu) and cumpoi(Val,mu,upper:T).

@@@@computing_pvalues#Computing P values
If x_obs is an observed value of a Poisson random variable with mean mu,
you can use cumpoi() to compute P-values for a test of H_0: mu = mu_0 as
follows:
     H_a       P-value
  mu > mu_0    cumpoi(x_obs,mu_0,upper:T)
  mu < mu_0    cumpoi(x_obs,mu_0)
  mu != mu_0   2*min(cumpoi(x_obs,mu_0),cumpoi(x_obs,mu_0,upper:T))

@@@@example#Example
Example:
  Cmd> 1 - cumpoi(13,9.5) # P(x > 13) = 1 - P(x <= 13), mu = 9.5
  (1)      0.10186

  Cmd> cumpoi(14,9.5, upper:T) # same
  (1)      0.10186

@@@@
See also cumbin().  See invgamma:"poisson_confidence_interval" for
information on computing a confidence interval for a Poisson mean.
@@@@______

====cumstu()#probabilities
%%%%
cumstu(x,df [,upper:T or lower:F]), x and df REAL, elements of df > 0
cumstu(x,df,delta [,upper:T or lower:F]), x, df > 0, delta REAL
%%%%
@@@@usage#Usage
cumstu(Val,df) computes P(t <= Val) where t is a Student's t random
variable with df degrees of freedom.  Val and df can be scalars,
vectors, matrices or arrays, but must have the same size and shape if
neither is a scalar.  When both are scalars, the result is a scalar; if
there is a non-scalar argument, the result has the same size and shape
as that argument.

The degrees of freedom must be positive, but not necessarily integral.

cumstu(Val,df,upper:T) and cumstu(Val,df,lower:F) compute upper tail
probabilities P(t >= Val).  The result is mathematically equivalent to 1
- cumstu(Val,df) but may be more accurate for large Val.

Two tailed P values for an observed t statistic Val can be computed with
the macro twotailt(Val,df) or as 2*cumstu(abs(Val),df,upper:T)).

@@@@example_1#Example
Compute two-tail P-value of H_0: mu = 10 using sample mean xbar and
standard deviation s from sample of size n:
  Cmd> 2*cumstu(abs(sqrt(n)*(xbar-10)/s), n-1, upper:T) #2-tail P-value

@@@@non_central_t#Non central t
cumstu(Val,df,delta) computes P(t <= Val) where t is a non-central
Student's t random variable with df degrees of freedom and noncentrality
parameter delta.  All three arguments can be scalars, vectors, matrices
or arrays, but any non-scalar arguments must have the same size and
shape which will be the size and shape of the result.

cumstu(Val,df,delta,upper:T) computes the upper tail probability
P(t >= Val).

When Val = (xbar - mu_0)/(s/sqrt(n)) is computed from a random sample of
size n from N(mu_a, sigma^2), delta = sqrt(n)*(mu_a - mu_0)/sigma.

@@@@example_2#Example
Compute the power of a one-tail 5% t-test of H_0: mu = 10 vs H_a: mu >
10 when mu = 15:
  Cmd> cumstu(invstu(.05,n-1,upper:T),n-1,sqrt(n)*(15-10)/sigma,upper:T)

@@@@see_also#Cross references
See also twotailt(), invstu(), subtopic cumF:"non_central_F", power()
and power2().
@@@@______

====cumstudrng()#probabilities,comparisons
%%%%
cumstudrng(x, ngroup, errorDf [,epsilon:eps] [,upper:T or lower:F])
  where x is REAL, elements of ngroup integers >= 2, elements of errorDf
  >= 1, eps > 0 small
%%%%
@@@@usage#Usage
cumstudrng(x, K, Df) computes the probability that Q <= x, where Q is a
Studentized range based on K normal variates and an independent estimate
of variance with Df degrees of freedom.  All three arguments must be
REAL.  K must consist of integers >= 2, and the elements of Df must be
>= 1, not necessarily integers.  The value is 0 for any x <= 0.  For any
element of Df > 1000, the asymptotic value (Df = infinity) is used.

Any of the arguments x, K or Df that are not scalars must be vectors,
matrices or arrays all of the same size and shape.

cumstudrng(x,2,Df) should be the same as 2*cumstu(x/sqrt(2),Df) - 1
except for computational error.

cumstudrng(x, K, Df, upper:T) and cumstudrng(x, K, Df, lower:F) compute
the upper tail probability P(Q >= x).  The result is equivalent to 1 -
cumstudrng(x,K,Df).

@@@@test_of_anova_hypothesis#Test of ANOVA hypothesis
When you have K independent normal samples of size n, all with the same
variance, you can test the null hypothesis that all means are equal by
the studentized range statistic computed as Q <- (max(xbars) -
min(xbars))/sqrt(Ssq/n).  This is an alternative to the ANOVA
F-statistic.

You can compute the P-value based on Q as cumstudrng(Q,K,K*(n-1),
upper:T).  Here xbars is a vector containing the K sample means and Ssq
is the pooled estimate of variance.  See invstudrng() for computing
critical values for Q.

@@@@epsilon_keyword#Keyword 'epsilon'
cumstudrng(x, K, Df, epsilon:eps [,upper:T or lower:F]), where eps is a
small positive scalar, does the same computation with accuracy
influenced by eps.  The smaller the value of eps, the more accurate the
result should be, but the longer it will take to compute it.  The
default value of eps is 0.0000001.

@@@@see_also#Cross references
See also invstudrng(), cumstu().
@@@@______

====customize%#control,general
%%%%
Type help(customize) for information on using environmental variable
  MACANOVA or preparing a special startup file
%%%%
@@@@introduction#Introduction
You can alter how MacAnova works either by using command line options
when launching MacAnova or by setting options once MacAnova has started.
You can automate these approaches by setting an environmental variable
MACANOVA and/or by preparing a startup file MacAnova.ini.txt. 

One common reason doing this is to add additional search paths for
macros, help, and files.  Also, on Unix/Linux, it may be necessary to
set the directory where MacAnova lives by using the -appdir option.

@@@@environmental_variable_macanova
                    Environmental variable MACANOVA
MacAnova looks for an environmental variable MACANOVA.  Its value should
be a list of command line options such as '-l 26 -w 75 -q' (see topic
'launching' for details on command line options).  These are, in effect,
prepended to any command line options that you use and thus are can be
overridden by options on the command line.  Some care may be needed
when quoting arguments with embedded spaces.  Also, it may be necessary
to double any backslashes used in directory paths.

DOS/Windows example: add another search directory and set dumb plots to
be 26 lines and 75 columns.  On Windows NT/2000/XP, right click on
"My Computer", then select "Properties", then select "Environment" (you
may need to select "Advanced" on some systems).  Then add a new variable
MACANOVA with value -l 26 -w 75 -path c:\macanova\macros
On earlier systems you can add a line like the following in your
AUTOEXEC.BAT file.
  SET MACANOVA=-l 26 -w 75 -path c:\macanova\macros

Unix/Linux example: set the application directory and add a directory to
the search path.  The method for setting environment variables depends
on the shell that you use.  For csh or a variant such as tcsh, add a line
similar to the following to the .chsrc file in your home directory:
  setenv MACANOVA '-path ~/mymacros -appdir /usr/local/macanova'
For sh, bash, or ksh, add a line similar to the following to the .profile
file in your home directory:
  MACANOVA='-path ~/mymacros -appdir /usr/local/macanova';export MACANOVA

Another use for MACANOVA is to make sure some standard macros are read
in or variables created by including '-e Command' in the environmental
variable (see 'launching').  For example, in Unix/Linux, one of
  setenv MACANOVA "-e getmacros(ffplot,tsplot,spectrum,quiet:T)" [csh]
or
  MACANOVA="-e getmacros(tsplot,ffplot,quiet:T)";export MACANOVA [sh]
ensures macros tsplot() and ffplot() will always be available.  Warning:
The command cannot contain any spaces or tabs.

@@@@using_startup_file
                  Customizing by using a startup file
When MacAnova is launched, it searches for a "startup" file with a
special name: MacAnova.ini.txt  MacAnova searches in the default
directory and any directories listed in character vector DATAPATHS.
If it is found, MacAnova assumes the initialization file contains
MacAnova commands and executes it silently as a batch file before the
first prompt (see batch(), launching).

See topic 'launching' for information on how to specify an alternative
startup file using command line flag -f.  See topic 'DATAPATHS' for a
description of setting the search path.

The use of a startup file is completely optional.  If you have one, you
can put commands in it to set options such as the default output
formatting, file names to replace the default values of variables
DATAFILE, MACROFILES, DATAPATHS (see topic 'DATAPATHS'), and HOME (see
topic 'file_names') and the units (radians, degrees, or cycles) to be
used by trigonometric functions (see topic 'options').  You can also
include commands to create macros or read in macros that will thus
always be available whenever you launch MacAnova.

Note: setoptions(prompt:newprompt) has no effect in a startup file.  See
topics setoptions(), 'options'.

The version of the startup file distributed with MacAnova does nothing
as it stands, since every action in it is in an if(F){...} clause.  You
can activate actions in the file by editing it to change some or all of
the if(F){...} to if(T){...} using any text editor.  If you use a word
processor, the file must be saved as a text or ASCII file.

@@@@tektronix_emulation#Tektronix emulation
If you run a Unix/Linux version of MacAnova through a terminal emulating
program that can switch into and out of Tektronix 4014 emulation mode,
you may want to use a startup file that sets option 'tektest' to specify
the character strings that control such switches.  See subtopic
'options:"tektest"'.  This is not necessary when you are running in an
xterm window.

@@@@example_startup_file#Example startup file
Here is a simple example of a possible MacAnova startup file (the line
numbers are for reference but are not part of the file)

Line #
  1    setoptions(nsig:6,angles:"cycles",pvals:T,fstats:T,restoredel:F)
  2    DATAFILE <- "timeser.dat"
  3    addmacrofile("mytser.mac")
  4    adddatapath("C:\\Time Series\\Data") #Windows form
  5    ls <- macro("listbrief($0)")
  6    if(isdefined(DEGPERRAD)){delete(DEGPERRAD,lockedok:T)}

If this were your startup file, it would have the following effects:
Line 1:
  Output will be printed with 6 significant digits (option 'nsig')
  Trigonometric functions will assume that angles are measured in cycles
    with 1 equivalent to 2*pi (option 'angles')
  Output from GLM functions such as anova(), regress(), and glmfit()
    will include P values, and where appropriate, F-statistics (options
    'pvals' and 'fstats')
  Command restore() will not delete existing variables unless they are
    overwritten or unless keyword phrase 'delete:T' is used on restore()
    (option 'restoredel')
Line 2:
  Pre-defined CHARACTER variable DATAFILE will be redefined to be
    "timeser.dat".  This will result in getdata() retrieving data 
    from file "timeser.dat".
Line 3:
  Prepend "mytser.mac" to pre-defined CHARACTER vector MACROFILES,
    ensuring that getmacros() will search file mytser.mac before the 
    standard macro files.
Line 4:
  Prepend "C:\\Time Series\\Data" to predefined CHARACTER variable 
    DATAPATHS making it the first search directory.  On Unix/Linux
    might be something like "~/TimeSeries/Data", and on Mac OS 9
    it might be "MyDisk:Time Series:Data".  See topic 'DATAPATHS'.
Line 5:
  Macro ls will be an "alias" for command listbrief()
Line 6:
  Pre-defined REAL constant DEGPERRAD with value 180/pi will be deleted.
  'lockedok:T' is required since DEGPERRAD is a locked variable.
@@@@______

====data_files%#variables,files,input,output
%%%%
Type help(data_files) for general information on data files MacAnova can
  read.
Type help(matread_file) for information on the format of files readable
  by matread() and read().
Type help(vecread_file) for information on the format of files readable
  by vecread() and readcols().
Type help(macro_files) for information on the format of files readable
  by macroread() and read().
Type help(files) for information on file names, abbreviated names of the
  form "~/fileName" and default directories or folders.
%%%%
@@@@introduction#Introduction
Any data file that can be read by MacAnova must be a plain text or ascii
file.  If you create it in a word processor, be sure to save it as a
text or ascii file.

All versions of MacAnova correctly read text files in DOS and Windows
format (lines separated by carriage return and linefeed code), in
Macintosh format (lines separated only by carriage return code), and in
Unix/Linux format (lines separated only by linefeed code).

@@@@option_maxlinelen#Option 'maxlinelen;
The only known limitation is that no more than a fixed number of
characters will be scanned in any single line.  This number is
determined by option 'maxlinelen' whose default in most versions is
2000.  If by some chance, you need to read a file containing lines
longer than this, you can increase it by, say

  Cmd> setoptions(maxlinelen:5000)

@@@@see_also#Cross references
See topic 'vecread_file' for information on files containing a single
unstructured REAL or CHARACTER data set that can be read by vecread()
and readcols().

See topic 'matread_file' for information on files of named REAL,
LOGICAL, or CHARACTER data sets or structures that can be read by
matread() and read().  Data sets may contain coordinate labels and have
descriptive notes.  No single line can have more than 50 data items.

See topic 'macro_files' for information on files that can be read by
macroread() and read().

See topic 'files' for technical information on file names, default
directories or folders, and abbreviated file names of the form
"~/filename".

See topic 'DATAPATHS' for information on where MacAnova searches for
files.

See also matread(), read(), vecread(), readcols(), and macroread().
@@@@______

====DATAPATHS%#files,input,output
%%%%
Type help(DATAPATHS) for information on CHARACTER vector DATAPATHS and
  how it specifies where MacAnova searches for files.
%%%%
@@@@description#Description
This topic describes how variable DATAPATHS determines where MacAnova
searches for files when you use a command such as read(), matread(),
vecread() or macroread() to read a file.  For all such commands, the
first argument is a CHARACTER scalar or quoted string specifying a file
name.  See topic 'file_names'.

DATAPATHS must be a CHARACTER scalar or vector.  Each element must be
the name (path) of a directory, ending with a separator character 
(you may use '/' on all platforms, '\' in Windows or MSDOS, and ':' on
Mac OS 9).  See topic 'file_names' for information on path names.

@@@@search_behavior#Search behavior
MacAnova first looks for the file in the default directory or folder
(see topic 'files').

If the file is not found in the default directory, MacAnova searches
for it in the directory or folder whose name is in DATAPATHS[1], then in
DATAPATHS[2] and so on.  If the file is not found in any of these, you
are informed that the file could not be opened.

@@@@adddatapath_macro#Macro adddatapath()
You can use macro adddatapath() to add directories or folders to the
start or end of DATAPATHS.  See adddatapath().

@@@@pre_defined_value#Pre defined value
On windowed versions of MacAnova, DATAPATHS is initialized to have two
elements.  The first element is a standard place for MacAnova files in
the user's directory.  This is the MyMacAnovaFiles directory in the
user's home directory.  (The home directory is well defined on Mac OS X
and Unix/Linux systems; various versions of Windows have home
directories for users, often in the Documents and Settings directory.)
The second element is a standard directory in the MacAnova installation.
(See the option -appdir under topic 'launching'.)

@@@@changing_the_value#Changing the value
You can change the defaults by setting DATAPATHS in a start up file, or
by setting environmental variable MACANOVA, or by command line options.
See topics 'customize' and 'launching'.  
@@@@______

For compatibility with earlier versions of MacAnova, if variable
DATAPATHS does not exist, variable DATAPATH is substituted, if it
exists.

                                Examples
@@@@windows_dos_example#Windows/DOS example
Windows and DOS:
  When DATAPATHS is vector("A:/SURVEY/", "C:/MACANOVA/"),
  read("mydata.dat") first tries to read MYDATA.DAT in the default
  directory or folder and then, if not successful, tries to read
  A:\SURVEY\MYDATA.DAT and C:\MACANOVA\MYDATA.DAT.

@@@@unix_linux_example#Unix/Linux and Mac OS X example
Unix/Linux:
  When DATAPATHS is vector("/users/joe/survey/", "/usr/lib/macanova/"),
  read("mydata.dat") first tries to read mydata.dat in the current
  default directory, and then, if not successful, it tries to read file
  /users/joe/survey/mydata.dat and /usr/lib/macanova/mydata.dat.
@@@@______

====delete()#variables,character variables
%%%%
delete(var1[ ,var2, ...] [,all:T, real:T or F,char:T or F,\
  logical:T or F, structure:T or F,macro:T or F, graph:T or F,\
  lockedok:T, silent:T]), F's used only with all:T
delete(var, return:T [,invisible:T])
%%%%
@@@@usage#Usage
delete(var1,var2,...,vark) deletes the variables given as arguments and
frees the memory they use for other purposes.  The variables can be of
any type including MACRO or GRAPH.  It is an error if any arguments are
'locked'.  See subtopic 'variables:"locked_variables"' and topics
lockvars() and unlockvars().

delete(var1,var2,...,vark, lockedok:T) does the same, even if one or
more of the variables are locked.

@@@@deleting_by_attributes#Deleting by attributes
You can use keywords 'real', 'char', 'logical', 'structure', 'macro',
'graph' and 'all' with LOGICAL values to delete classes of variables.

For example, delete(real:T, logical:T [,lockedok:T]) deletes all REAL
and all LOGICAL variables and delete(all:T, macros:F [,lockedok:T])
deletes everything except macros.  It is illegal to have both keyword
phrases specifying attributes and variables as arguments.

@@@@return_and_invisible_keywords#Keywords 'return' and 'invisible'
delete(var, return:T) deletes variable var but returns a copy as value.
This usage is most common as the last command in a macro when the value
the macro is supposed to be var, as in the following
  Cmd> mymacro <- macro("@tmp <- ($1)+($2)
         print(describe(@tmp))
         delete(@tmp,return:T)", dollars:T)

mymacro(x,y) prints descriptive statistics for x+y and returns x+y as
value, automatically deleting the temporary variable.  See also macro(),
'macro_syntax' and 'macros'.

delete(var, return:T, invisible:T) does the same except the value is
returned as an "invisible" variable (see 'variables').  The value can be
assigned to a variable but will not automatically print when it is not
assigned.  'invisible:T' is illegal without 'return:T'.  See topic
'variables:"invisible"'.

delete(var, return:F) is also legal and has the same effect as
delete(var).

@@@@silent_keyword#Keyword 'silent'
delete(..., silent:T) suppresses all warning messages.  'silent:T' must
be last argument.

@@@@deleting_special_variables#Deleting special variables
delete(CLIPBOARD) does not actually delete special variable CLIPBOARD
but clears its contents without affecting the system clipboard in any
way.  In the GTK version, delete(SELECTION) behaves the same.  See
topic 'CLIPBOARD'.

delete(GRAPHWINDOWS) does not actually delete special structure
GRAPHWINDOWS, but sets all its components to NULL, changing their names.
It does not affect what is displayed in the corresponding graphics
windows.  See topic 'GRAPHWINDOWS'.

@@@@see_also#Cross references
See also topics list(), listbrief().
@@@@______

====describe()#descriptive statistics
%%%%
describe(data [, silent:T, excludeM:T, all:T, fivenum:T, n:T|F, min:T|F,
  max:T|F, q1:T|F, q2:T|F, median:T|F, mean:T|F, var:T|F, stddev:T|F,
  m3:T|F, m4:T|F, g1:T|F, g2:T|F, iqr:T|F, range:T|F]), where data is
  REAL or a structure with REAL components; F's should be used only with
  all:T or fivenum:T.
%%%%
@@@@usage#Usage
describe(Data) computes statistics describing the data in the REAL
vector or array Data.

The value of describe(Data) is a structure with following components:
        n            sample size, excluding MISSING values
        min          minimum
        q1           Q1 = lower quartile
        median       M = median
        q3           Q3 = upper quartile
        max          maximum
        mean         average
        var          variance (with divisor of n-1)

By default Q1 and Q3 are computed as the medians of the lower and upper
halves of the data, *including* the median in both halves when n is odd.
Keyword phrase excludeM:T (see below) changes this definition so that Q1
and Q3 are computed as medians of the lower and upper halves *excluding*
the median.

describe(Data, silent:T) does the same, but any warning messages about
MISSING values or overflows are suppressed.

describe() can compute additional statistics including the standard
deviation and the interquartile range.  See below.

@@@@computing_specific_statistics#Computing specific statistics
You can specify particular statistics to compute using keyword phrases.
For example, describe(Data, mean:T) has the same result as
describe(x)$mean, except that no unwanted statistics are computed, and
describe(Data, mean:T,var:T) returns a structure with components 'mean'
and 'var' without computing other statistics.

When only one statistic is requested, the result is a REAL variable and
not a structure.

You can use 'm1' instead of 'mean' and 'q2' instead of 'median' when
specifying what to compute; however, when other statistics are also
computed, the components still have names 'mean' and 'median'.  For
example, describe(x,m1:T,q2:T) is equivalent to describe(x,mean:T,
median:T).

@@@@fivenum_keyword#Keyword 'fivenum'
describe(x, fivenum:T) is equivalent to describe(x,min:T,q1:T,median:T,
q3:T,max:T), that is, it computes the five number summary consisting of
the extremes and quartiles.

If you want additional statistics, say, the mean, use describe(x,
fivenum:T,mean:T).

If you want to suppress one or more of the five numbers, say the
extremes, use describe(fivenum:T,max:F,min:F).

@@@@additional_statistics#Additional statistics
There are other statistics that can be computed only by using keyword
phrases.
       stddev        standard deviation = sqrt(var)
       m2            sum((x-xbar)^2)/n = s2/n = (n-1)*var/n
       m3            sum((x-xbar)^3)/n = s3/n
       m4            sum((x-xbar)^4)/n = s4/n
       g1            coefficient of skewness (see below)
       g2            coefficient of kurtosis (see below)
       range         maximum - minimum
       iqr           IQR = Q3 - Q1 = interquartile range

Some text books give m2 = s2/n as the definition of sample variance
instead of the value of var = s2/(n-1).

Example:
  Cmd> describe(x, g1:T, g2:T)

returns a structure containing the skewness and kurtosis of x in
components g1 and g2.  See below for their exact definitions.

@@@@all_keyword#Keyword 'all'
describe(Data, all:T) returns a structure with the 8 standard components
plus components stdev, m2, m3, m4, g1, g2, range and iqr.  You can
suppress any component by, for example, median:F.

Example:
  Cmd> describe(Data, all:T, q1:F, median:F, q3:F, silent:T)

returns a structure containing all statistics except the median and
quartiles.  Because 'silent:T' is an argument, no warning is printed if
Data contains MISSING values.

@@@@excludeM_keyword#Keyword 'excludeM'
describe(Data, excludeM:T ...) is a variant, except that Q1 and Q3 are
computed as medians of the lower and upper half of the data, *excluding*
the median when n is odd, and the IQR is computed from these modified
quartiles.  This corresponds with the definition of quartiles in some
statistical texts, including David S. Moore, The Basic Practice of
Statistics.

'excludeM:T' modifies results only when the number n of non-MISSING
values is odd and one or more of Q1, Q3 or IQR is computed.

@@@@case_of_keyword_names#Case of keyword names
The case, upper or lower, of letters is ignored in describe() keyword
names.  For example, Q1:T and q1:T are equivalent.  This currently
differs from the behavior of most other functions.  The names of
components are all lower case.

@@@@multidimensional_argument#Multidimensional argument
When Data is multidimensional (a matrix or array) with dimensions n1,
n2, ..., nk, each component of the result (or the result itself when
only one statistic is requested) is an array with dimensions n2, n3,
..., nk, that is, it has one fewer dimensions than Data.  Each statistic
describes all values with the last k-1 subscripts fixed (a column when
Data is a matrix).  In particular, when Data is a true matrix (exactly 2
dimensions), the component is a vector.  For example, when Data is a
true matrix, describe(Data, mean:T) is a vector, but
sum(Data)/nrows(Data) is a row vector (matrix with 1 row).

When Data is a vector or matrix, you can also use tabs(Data [,keywords])
to compute some of the statistics computed by describe() (not q1,
median, q3, m2, m3, m4, g1, g2, range or iqr).  See tabs().

@@@@structure_argument#Structure argument
When Data itself is a structure, each component of the result (or the
result itself when only one statistic is requested) is itself a
structure with the same shape as Data, whose components contain summary
values for the corresponding component of Data.

@@@@examples#Examples
Examples:
  Cmd> xbar <- describe(x, mean:T); sx <- describe(x, stddev:T)
compute the mean and standard deviation of x.

  Cmd> medians <- describe(split(y,a), median:T) # or MEDIAN:T
and
  Cmd> medians <- describe(split(y,a))$median # not $MEDIAN
both compute a structure, each of whose elements is the median of the
values of y corresponding to a level of factor a.  The first does less
computing of results you aren't saving.

  Cmd> describe(x, mean:T, var:T) # or Mean:T, VAR:T
and
  Cmd> describe(x)[vector(7,8)]

are equivalent, except the latter does much unnecessary computing
because it computes and then discards the extremes, the quartiles and
the median.

@@@@skewness_and_kurtosis#Skewness and kurtosis
Skewness g1 = k3/k2^1.5 and kurtosis g2 = k4/k2^2 are computed from
Fisher's k-statistics k2, k3 and k4 defined as

  k2 = var = s2/(n - 1)
  k3 = n*s3/((n - 1)*(n - 2)), and
  k4 = (n*(n + 1)*s4 - 3*(n - 1)*s2^2)/((n - 1)*(n - 2)*(n - 3))

g1 and g2 similar to, but not identical to, sqrt(beta1) = m3/m2^1.5 and
beta2 = m4/m2^2 - 3 which are also used to measure skewness and
kurtosis.

Expressed in terms of sqrt(beta1) and beta2:

  g1 = (sqrt(n*(n - 1))/(n - 2))*sqrt(beta1)
  g2 = ((n^2 - 1)/((n - 2)*(n - 3)))*(beta2  +  6/(n + 1))

When n <= 2, g1 is computed to be 0.  When n <= 3, g2 is computed to be
0.

g1 and g2 are sometimes used to test the null hypothesis that a sample
comes from a normal population.  If the data are a random sample from a
normal distribution, then g1 and g2 have mean 0 and

  V[g1] = 6*n*(n - 1)/((n - 2)*(n + 1)*(n + 3))
  V[g2] = 24*n*(n - 1)^2/((n - 3)*(n - 2)*(n + 2)*(n + 5))

@@@@see_also#Cross references
See also topics 'structures', 'keywords'.
@@@@______

====descriptive()#descriptive statistics
%%%%
descriptive(data [options to describe()] [structure:T|F])
%%%%
@@@@usage#Usage
descriptive() is a temporary front end to describe(), adding
the single options structure:T|F.  If structure:T is chosen,
the output is just as if you had given the arguments to
describe().  If structure:F is chosen, then the result is
formed as a labelled vector or matrix rather than as a
structure.

descriptive() will only analyze one variable at a time.

See also describe().
@@@@______


====design%#anova,glm,regression
%%%%
Type 'help(design)' for information on functions and macros useful in
experimental design

Type 'help(designhelp)' for information on getting help on the macros in
file design.hlp
%%%%
Functions for sample size and power computations:
  power(), power2(), samplesize(), cumF(), cumstu(), cumchi()

Type, for example, 'usage(power)' or 'help(power)', to get a thumbnail
sketch or a complete description of power().

@@@@contents_of_macro_file_design.mac#Contents of macro file Design.mac
File design.mac, distributed with MacAnova, contains the following
macros:
                 Macros Useful in Designing Experiments
  aliases2     Gets aliases in fractioned 2 series
  aliases3     Gets aliases in fractioned 3 series
  allaliases2  Complete aliases structure in fractioned 2 series
               factorial
  choosegen2   Chooses generators for a 2 series fractional factorial
  choosedef2   Chooses defining contrasts for a blocked 2 series
               factorial
  confound2    Confounds a 2 series factorial into blocks
  confound3    Confounds a 3 series factorial into blocks
  ems          Computes the expected mean squares for the terms in the
               ANOVA of a model some of whose terms are random
  ffdesign2    Determines factor/level combinations to use for
               fractioned 2 series

                    Macros for Statistical Analysis
  all3anova    Fits all hierarchical models in a three factor anova and
               sorts them by Cp
  all4anova    Fits all hierarchical models in a four factor anova and
               sorts them by Cp
  boxcoxvec    Gets the error SS for several boxcox transformations
  interactplot Make interaction plots of marginal means in a factorial
  interblock   Recover interblock information in an incomplete block
               design
  mixed        Computes an "ANOVA" table for a model some of whose
               factors are random
  pairwise     Does paired comparisons and generates an "underline"
               diagram
  quadmax      Finds the location of the maximum of a quadratic
               function, with optional linear equality and inequality
               constraints on the solution
  randsign     Does a permutation paired t-test
  randt        Does a permutation two-sample t-test
  randt2       Carry out a permutation two sample t-test combining
               values from two fectors (uses randt)
  rscanon      Does canonical analysis of 2nd order response surface
               design
  reml         Perform restricted maximum likelihood analysis of a model
               with fixed and random terms
  sidebyside   Make a side-by-side plot of effects
  varcomp      Computes the "ANOVA" estimates of random effects
               variances in mixed effects analysis of variance

                 Auxiliary macros used by other macros
  colproduct   Computes all element-wise products of the columns of two
               matrices (used by ems)
  makemat      Computes various basis matrices (used by ems)
  quadmaxlin   Finds the maximum of x'Ax + b'x subject to Cx = y (used
               by quadmax)

These can be retrieved by, for example, getmacros(boxcoxvec) or
boxcoxvec <- macroread("design.mac","boxcoxvec").  In a standard
installation of macanova, they are available simply by using them.

You can get information on these macros by help() or usage() or, for
example, by designhelp(makemat, varcomp) or designhelp(makemat, varcomp,
usage:T).  See topic designhelp() for details.

@@@@see_also#Cross references
See help() for information on direct use of help() to retrieve help
information from design.hlp.

See also topics 'macros', macroread(), getmacros(), help(), usage(),
macrousage().
@@@@______

====designhelp()#general,anova,glm,regression
%%%%
designhelp(topic1 [, topic2 ...] [,usage:T] [,scrollback:T])
designhelp(topic, subtopic:Subtopics), CHARACTER scalar or vector
  Subtopics
designhelp(topic1:Subtopics1 [,topic2:Subtopics2 ...])
designhelp(key:Key), CHARACTER scalar Key
designhelp(index:T [,scrollback:T])
%%%%
@@@@usage#Usage
designhelp(Topic1 [, Topic2, ...]) prints help on topics Topic1, Topic2,
... related to macros in file design.mac.  The help is taken from file
design.hlp.

designhelp(Topic1 [, Topic2, ...] , usage:T) prints usage information
related to these macros.

designhelp(index:T) or simply designhelp() prints an index of the topics
available using designhelp().  Alternatively, help(index:"design") does
the same

designhelp(Topic, subtopic:Subtopic), where Subtopic is a CHARACTER
scalar or vector, prints subtopics of topic Topic.  With subtopic:"?", a
list of subtopics is printed.

designhelp(Topic1:Subtopics1 [,Topic2:Subtopics2], ...), where
Suptopics1 and Subtopics2 are CHARACTER scalars or vectors, prints the
specified subtopics.  You can't use any other keywords with this usage.

In all the first 4 of these usages, you can also include help() keyword
phrase 'scrollback:T' as an argument to designhelp().  In windowed
versions, this directs the output/command window will be automatically
scrolled back to the start of the help output.

@@@@key_keyword#Keyword 'key'
designhelp(key:key) where key is a quoted string or CHARACTER scalar
lists all topics cross referenced under Key.  designhelp(key:"?") prints
a list of available cross reference keys for topics in the file.
@@@@______

designhelp() is implemented as a predefined macro.

@@@@see_also#Cross references
See help() for information on direct use of help() to retrieve
information from design.hlp.
@@@@______

====det()#matrix algebra
%%%%
det(x [, mantexp:T, quiet:T]), where x is a REAL square matrix with no
  MISSING values.
%%%%
@@@@usage#Usage
det(x) computes the determinant of the square REAL matrix x.  MISSING
values are not allowed in x.  When x is singular within rounding error,
det(x) is 0 and a warning message is printed.

det(x,mantexp:T) does the same, but returns the result in base 10
mantissa and exponent form.  For instance, when det(x) = -5.67832e+123,
det(x,mantexp:T) returns vector(-5.67832, 123).  This allows you to find
a determinant whose value is either too large or too close to 0 to be
represented.

det(x [,manexp:T], quiet:T) does the same, but suppresses the warning
message when x is singular.

@@@@see_also#Cross references
See also topics 'matrices', trace().
@@@@______

====diag()#matrix algebra,variables
%%%%
diag(A), A a matrix.
%%%%
@@@@usage#Usage
diag(a) creates a vector consisting of the diagonal elements a[1,1],
a[2,2], ... of matrix a, which does not need to be square.  The length
of the result is min(nrows(a),ncols(a)).  Matrix a may be REAL (most
common), LOGICAL or CHARACTER.

diag(a) is defined for an array with more than 2 dimensions, as long as
there are only two dimensions with size > 1, interpreted as the number
of rows and columns.  For example, after manova(model) command,
diag(SS[3,,]) is the diagonal of the sums of squares and cross-products
matrix associated with term 3 in the model.

@@@@see_also#Cross references
See also dmat(), trace(), 'matrices'.
@@@@______

====digamma()#transformations
%%%%
digamma(x), x REAL with positive elements or a structure with REAL
  components with positive elements.
%%%%
@@@@usage#Usage
digamma(x) returns the digamma function (first derivative of
log(gamma(x))) of the elements of x, when x is a REAL scalar, vector,
matrix or array with positive elements.  The result has the same shape
as x.

digamma(x) is equivalent to polygamma(x,0).

@@@@structure_argument#Structure argument
When x is a structure, all of whose non-structure components are REAL
with positive elements, digamma(x) returns a structure of the same shape
and with the same component names as x with each non-structure component
transformed by digamma().

@@@@character_argument#Character argument
digamma(x) can also be used when x is a CHARACTER variable.  The result
is a CHARACTER variable of the same shape as x describing the
transformation.  See the example below.

Any element of x that is "" or starts with '@', '(', '[', '{', '<', '/'
or '\' is not modified.  This can be useful for creating labels for a
transformed variable.

@@@@examples#Examples
Examples:
  Cmd> digamma(run(10)) # or polygamma(run(10),0) or polygamma(run(10))
  (1)    -0.57722     0.42278     0.92278      1.2561      1.5061
  (6)      1.7061      1.8728      2.0156      2.1406      2.2518

  Cmd> digamma(vector("x","y")) # CHARACTER argument
  (1) "digamma(x)"
  (2) "digamma(y)"

@@@@see_also#Cross references
See also polygamma(), lgamma(), 'transformations'

====dim()#variables,null variables
%%%%
dim(x), x a scalar, vector, matrix, array, structure, macro or GRAPH
  variable.
%%%%
@@@@usage#Usage
dim(x) returns a vector containing the dimensions of x.  For example,
when x is a vector of length 10, dim(x) has value 10.  When x is a 5 by
7 matrix, dim(x) has value vector(5,7) and dim(x)[1] and dim(x)[2] are 5
and 7, respectively.  When x is an array with k dimensions, dim(x) is a
vector of length k.

When x is a macro or GRAPH variable, dim(x) is 1.

When x is a NULL variable, dim(x) is 0. This is a change from version
4.07 and earlier when dim(NULL) was NULL.

@@@@structure_argument#Structure argument
When x is a structure, dim(x) is a structure, each of whose components
is a structure with the same shape as x.  Suppose N is the largest
number of dimensions of any component of x or is 1 if all non-structure
components of x are NULL.  Then dim(x) has N components named 'dim1',
'dim2', ....  When xcomp is a non-NULL and non-structure component of x,
the corresponding component of dim(x)[j], that is, x$dimj, is
dim(xcomp)[j] when ndims(xcomp) <= j or 0 when ndims(xcomp) < j.  When
xcomp is NULL, the corresponding component of dim(x)[j] is 0.

@@@@examples#Examples
Examples:
  dim(4) is 1
  dim(run(6)) is 6
  dim(matrix(run(20),5)) is vector(5,4)
  dim(array(run(24),2,3,4)) is vector(2,3,4)
  dim(structure(run(6),structure(matrix(run(6),3),NULL)) is
   structure(dim1:structure(6,structure(3,0)),
     dim2:structure(0,structure(2,0)))

@@@@see_also#Cross references
See also topics length(), ndims(), 'structures', 'NULL'.
@@@@______

====dmat()#matrix algebra,variables
%%%%
dmat(n,val), n > 0 integer, val a REAL, CHARACTER or LOGICAL scalar
dmat(vec), vec a REAL, CHARACTER or LOGICAL vector.
%%%%
@@@@usage#Usage
dmat(n,val), where n is a positive integer and val is a scalar
(length(val) = 1), produces an n by n diagonal matrix with val down the
diagonal.

dmat(a) where a is a vector of length n, a n by 1 matrix, or a 1 by n
matrix, produces a n by n diagonal matrix with the elements of a down
the diagonal.

Note: This is a sort of inverse to diag() which extracts the diagonal
elements of a matrix.

@@@@example#Example
Example:
  Cmd> iden5 <- dmat(5,1); iden5 # or dmat(rep(1,5))
  (1,1)           1           0           0           0           0
  (2,1)           0           1           0           0           0
  (3,1)           0           0           1           0           0
  (4,1)           0           0           0           1           0
  (5,1)           0           0           0           0           1

This is the 5 by 5 identity matrix

@@@@see_also#Cross references
See also diag().
@@@@______

====dos_windows%#general
%%%%
Type help(dos_windows) for a summary of features specific to DOS/Windows
versions of MacAnova.
%%%%
@@@@introduction#Introduction
There are two released versions of MacAnova for Windows.  The first runs
under Windows 98/NT/XP and includes the familiar multi-window features,
menus, dialogs, etc.  The second runs in a "command prompt" window (MS-DOS
window) and does not use any Windows features.  Both have the full range
of MacAnova commands.

This help topic first describes features or limitations specific to each
version and then describes things they have in common that are specific
to Windows systems.

@@@@windows_version
                        Windows version (CP)
This version is compiled using the Carapace library which in turn uses
the WxWidgets library. It requires a Win32 system such as Windows
98/NT/XP. It allows multiple command/output and high resolution graphics
windows and uses menus, dialogs, the mouse, and so forth in the usual
way.  Commands are typed into the lower pane of a command window, and
output appears in the upper pane.  Output and graphics windows can be
printed and/or saved to files.

Text in a command window can be copied to the clipboard.  Content of
a graphics window can be copied to the clipboard as a bitmap.  The
MacAnova variable CLIPBOARD is connected to text on the clipboard in
the sense that accessing CLIPBOARD returns a MacAnova string containing
the text content of the clipboard, and assigning to CLIPBOARD writes
text to the clipboard.

See topic 'carapace' for details about MacAnova for Windows.

The executable file is usually named MACANOCP.EXE.

shell(command,interact:F) and shell(command,keep:T) do not work under
Windows 3.1 and Windows 95.  It is possible that they work under Windows
NT, but that has not been tested.  shell(command,interact:T) and lines
prefixed with '!' appear to behave somewhat differently, depending on
the operating system.  Problems remain to be worked out.  See shell().

@@@@dos_version
                    DOS version (DJ)
The DOS version is compiled using the DJGPP development suite and 
requires a 80386 or better processor.  Although it runs under DOS, it
can access all available memory and has no limits on variable sizes.

The executable file is usually named MACANODJ.EXE.

The extended memory version works with a variety of graphic displays,
including VGA.  Keyword phrase screendump:fileName on plotting commands
allows you to create PCX files which can be edited under Windows and
included in word processor documents.

It has command editing implemented using the arrow keys and editor
commands based on either the Emacs or Vi editor commands (Emacs and Vi
are Unix/Linux editors).  See topic 'unix' for details.  The only
difference from the Unix/Linux version is that the special file for
customizing keymaps must be "INPUTRC" (not ".inputrc") in the same
directory as MACANODJ.EXE.

You can execute DOS commands by prefixing the line with '!' in the first
position after the prompt or by using the command shell().  
shell(cmd,keep:T) returns output from the program executed.  You must
use shell(cmd,interact:T) if the program executed requires any input.
When in doubt, use interact:T.  This feature appears to work somewhat
differently under Windows 95.

Macro edit() (see topic edit()) is predefined to allow easy editing of
macros and data without exiting Macanova.  By default it uses the DOS
program Edit but this can be changed by setting CHARACTER variable
EDITOR to the path name of a different editor.

@@@@features_in_common
            Features common to all Windows and DOS versions
MacAnova recognizes '/' in file names (for instance, c:/mv/macanova.dat
instead of c:\mv\macanova.dat).  This is desirable, since to use '\' in
a quoted string it must be doubled ("c:\\mv\\macanova.dat").  See
topic 'syntax'.

Various command line arguments are recognized, allowing automatic
restoring of a workspace, suppressing the banner, changing default file
names, etc.  On the Windows version, they allow initializing the
command/output window with the contents of a file.  See topic
'launching'.

MacAnova uses any default options or file or path names in environmental
variable MACANOVA.  See topic 'customize'.

The startup file is MacAnova.ini.txt in you MyMacAnovaFiles directory.
See topic 'customize'.

Unless you use command line option -home (see 'launching') or include
-home in environmental variable MACANOVA (see 'customize'), MacAnova
pre-defines CHARACTER variable HOME to be your home directory (for
example, c:\Documents and Settings\username on Win XP). HOME is used to
expand file names of the form "~/path" or "~\\path" by substituting the
value of HOME for '~'.  This allows you to refer to files such as
MacAnova.txt.ini as "~/MyMacAnovaFiles/Macanova.ini.txt", even if you
have changed directories.  If you redefine HOME, it changes the
expansion of "~/" and "~\\".  See topic 'files'.

Pre-defined variable DATAPATHS is initialized with two path names.  The
first is effectively "~/MyMacAnovaFiles" and the second is
"foo/SharedSupport", where "foo" is the full path to the directory that
includes the MacAnova program file.  If you use command line argument
"-appdir goo", then the "foo" in the second element of DATAPATHS is 
replaced by "goo".  You may prepend a search path to DATAPATHS at the
command line by using the option "-path pathName".  See topics
'DATAPATHS' and 'customize'.
@@@@______

====edit()#general
%%%%
edit(obj [, T] [,stripdol:F]), obj a macro or a REAL variable
edit(0)
edit([stripdol:T])
%%%%
@@@@usage#Usage
edit(obj) where obj is a REAL vector, matrix, array, or a macro, writes
a temporary file and invokes an editor to edit that file.  When editing
is done, edit() returns as value the edited contents of the file.  For
example, 'mymacro <- edit(mymacro)' allows you to change or correct
macro mymacro().  edit() is implemented as a macro which is pre-defined
only in some non-windowed versions of MacAnova.

When you change the dimensions of a vector, matrix, or array, you must
edit the header line to reflect the change before quitting the editor.

edit(obj,T) is equivalent to 'obj <- edit(obj)'.

@@@@stripdol_keyword#Keyword 'stripdol'
By default, when editing a macro, trailing '$$' on temporary variables
are stripped off for editing and then restored before returning.  To
suppress this, used edit(mymacro [,T], stripdol:F)

@@@@creating_new_macro#Creating new macro
mynewmacro <- edit([stripdol:F]) (with no non-keyword arguments) invokes
an editor on a temporary file with a header specifying a macro with a
single blank line.  You can enter and edit a macro, being sure to change
the number on line 1 to reflect the actual number of lines in the macro.
Unless stripdol:F is an argument, '$$' will be appended to any names
starting with '@'.

@@@@creating_new_vector#Creating new vector
x <- edit(0) invokes an editor on an empty temporary file and then
performs vecread() on that file, under the assumption that the user has
edited in data that may be read in this manner.  This allows you to use
an editor to enter data.

@@@@changing_default_editor#Changing default editor
You can specify the editor to be used by creating a CHARACTER variable
with name 'EDITOR' by, for example, EDITOR <- "emacs".  When EDITOR has
not been set, the default editor is "vi" on Unix/Linux and "edit" for
DOS.
@@@@______

Macro edit() is pre-defined only in the Unix/Linux versions and in the
extended memory DOS version of MacAnova.  Two forms of edit(), one for
Unix/Linux and one for DOS, are included with names editunix() and
editpc(), in file MacAnova.mac.txt distributed with MacAnova.

@@@@editing_in_windowed_versions#Editing in windowed versions
To edit a macro, say mymacro(), in a windowed version, first open a new
command/output window using Open on the File menu.  Then print the
macro in the new window in a form you can edit by:

  macrowrite(CONSOLE, mymacro, stripdol:T)

Then edit the macro, copy to the clipboard the entire macro including
the header line (mymacro MACRO DOLLARS) and trailer line (%mymacro%),
and then do the following:

  mymacro <- macroread(string:CLIPBOARD)

Then switch back to your original window to test it and use it.  It's
not necessary to open the extra window, but it makes it easier since you
can separate your editing from the use of the macro.

@@@@see_also#Cross references
See also topics macrowrite(), macroread(), 'CLIPBOARD'.
@@@@______

====eigen()#matrix algebra
%%%%
eigen(x [,maxit:N, nonconvok:T]), x a REAL symmetric matrix with no
  MISSING values, integer N > 0
%%%%
@@@@usage#Usage
eigen(x) computes an eigenvector/eigenvalue decomposition of the
REAL symmetric matrix x.  The result is a structure with two REAL
components, 'values' and 'vectors'.  It an error if x contains any
MISSING values.

Vector eigen(x)$values contains the eigenvalues in decreasing order
(eigen$values[i] >= eigen$values[i+1]).  If all you need are the eigen-
values, use eigenvals(x).

The columns of square matrix eigen(x)$vectors are the eigenvectors of x
with eigen$vectors[,j] corresponding to eigen$values[j].  The eigen-
vectors are orthonormal, even when there are repeated eigenvalues.

@@@@properties#Properties
From the properties of the eigenvalue/eigenvector decomposition of a
matrix,
  eigen(x)$vectors %*% dmat(eigen(x)$values) %*% eigen(x)$vectors'
should be the same as x, except for rounding error.

@@@@non_convergence
                            Non-convergence
It is possible for the algorithm used by eigen() not to converge,
although it rarely happens.  When it happens, the message
  ERROR: algorithm to compute eigenvalues in eigen() did not converge
is printed.  Keywords 'maxit' and 'nonconvok' may be helpful in this
situation.

@@@@maxit_and_nonconvok_keywords#Keywords 'maxit' and 'nonconvok'
eigen(x maxit:N), where N > 0 is an integer, computes the eigenvalues
and eigenvectors, but sets the maximum number of iterations in the
algorithm to N.  The default value is 30.  By using N > 30, this may
allow you to compute eigenvalues and vectors you can't otherwise

eigen(x [,maxit:N] ,nonconvok:T) does the same, except failure to
converge is not an error.  When convergence does not occur, no message
printed and NULL is returned.  You can use this in a macro to make it
possible to recover from failure to converge, perhaps by invoking
eigen() again using 'maxit' to increase the number of iterations.

Keyword phrases 'maxit:T' and 'nonconvok:T' may also be used on
eigenvals(), releigen() and releigenvals().

@@@@see_also#Cross references
See also eigenvals(), trideigen(), releigen(), and releigenvals().
@@@@______

====eigenvals()#matrix algebra
%%%%
eigenvals(x [,maxit:N, nonconvok:T]), x a REAL symmetric matrix with no
  MISSING values, integer N > 0
%%%%
@@@@usage#Usage
eigenvals(x) computes a REAL vector containing the eigenvalues of REAL
symmetric matrix x in decreasing order.  These are identical to
eigen(x)$values.  If you need eigenvectors, use eigen().

See eigen() for information on keyword phrases 'maxit:N' and
'nonconvok:T'.

@@@@see_also#Cross references
See also det(), trideigen(), releigen(), and releigenvals().
@@@@______

====else#syntax,control
%%%%
if (Logical1){command1;command2;...} [elseif (Logical2){...}] else{...}
%%%%
@@@@usage#Usage
'else' is a syntax element used in conjuction with 'if' and optionally
with 'elseif'.

A typical usage would be
  Cmd> if(x > 1){y <- 1}elseif(x < 0){y <- -1}else{y <- 0}

The immediately following '{' must be on the same line as 'else'.

Type help("if") for complete information.
@@@@______

====elseif#syntax,control
%%%%
if (Logical1){command1;command2;...} elseif (Logical2){...}[else{...}]
%%%%
@@@@usage#Usage
'elseif' is a syntax element used in conjuction with 'if' and optionally
with 'else'.

A typical usage would be
  Cmd> if(x > 1){y <- 1}elseif(x < 0){y <- -1}else{y <- 0}

The condition tested (x < 0 in the example) must be a scalar LOGICAL
variable or expression.  The immediately following '{' must be on the
same line as elseif.

Type help("if") for complete information.
@@@@______

====enter()#input
%%%%
x <- enter(val1 val2 val3 ...) , valI a number or ?, no separating
  commas
%%%%
@@@@usage#Usage
x <- enter(val1 val2 ...) is equivalent to x <- vector(val1, val2, ...)
allowing easy entry of data without the need to type commas.  val1,
val2, ... should be numbers or ?, not expressions or function values.

@@@@example#Example
Example:
  Cmd> wts <- enter(145.2 162.1 133.5 121.9 99.8 188.9)
or
  Cmd> wts <- enter(1452 1621 1335 1219 998 1889)/10
These are equivalent, but the second avoids the need to type decimal
points.
@@@@______

enter() is implemented as a pre-defined macro using vecread().

@@@@see_also#Cross references
See also topics vecread(), enterchars().
@@@@______

====enterchars()#input
%%%%
x <- enterchars(str1 str2 str3 ...) , strI a non-quoted sequence of
   visible characters, separated by spaces.
%%%%
@@@@usage#Usage
x <- enterchars(Str1 Str2 ...) is equivalent to x <- vector("Str1",
"Str2", ...)  allowing easy entry of CHARACTER data without the need to
type quotes (") or commas (,).  Str1, Str2, ... must consist of visible
characters which are not commas or '#' and be separated by spaces, tabs
or commas.

You cannot use enterchars() to enter CHARACTER elements which contain
commas or any kind of invisible characters such as spaces or tabs.

@@@@example#Example
Example:
  Cmd> names <- enterchars(Henry Susan Bill Rene)
@@@@______

enterchars() is implemented as a pre-defined macro using vecread().

@@@@see_also#Cross references
See also topics vecread(), enter().
@@@@______

====equal()#general,variables
%%%%
equal(a, b [,chknames:F,chklabels:T,chknotes:T,fuzz:eps,relative:T,\
  explain:T), a and b any two defined variables except GRAPH variables,
  eps > 0 a small REAL scalar

%%%%
@@@@introduction#Introduction
You can use equal() to test for exact or approximate equality of two
defined variables of any type except GRAPH.

@@@@usage#Usage
equal(arg1, arg2) returns True or False depending on whether or not arg1
and arg2 are exactly equal.  arg1 and arg2 can be any defined variables
except GRAPH variables, including macros, NULL variables, and
structures.

See below for keywords 'fuzz' and 'relative' which allow for approximate
equality and for keywords 'chknames', 'chklabels' and 'chknotes' that
control what non-data items are checked for equality.

If x is defined, equal(x,x) always returns True, even when x is a GRAPH
variable.

Two NULL variables are always treated as equal.

When arg1 and arg2 are structures, the are considered equal only if
every component or subcomponent is equal and component names are the same.

equal(arg1, arg2, explain:T) makes the same comparison but returns
structure(equal:T or F, why:Explanation), where Explanation is a
CHARACTER scalar that is either "Arguments are equal" or an explanation
of the inequality such as "Argument values differ" or "Component
dimensions differ".  In case of inequality, the first applicable reason
is given.  If arg1 and arg2 are unequal structures, the number of the
component or subcomponent where inequality was detected is part of the
explanation.

@@@@fuzz_and_relative_keywords#Keywords 'fuzz' and 'relative'
When you are comparing numerical results of computation, exact equality
may not be appropriate because real numbers are not perfectly
represented in the computer.  You can specify that REAL variables and
components are to be considered equal if the differences between their
elements are small enough, either in an absolute or relative sense.

equal(arg1, arg2, fuzz:epsilon), where epsilon > 0 is small, returns
True if all differences d = x1 - x2 of elements of REAL variables or
structure components satisfy abs(d) <= epsilon.

equal(arg1, arg2, fuzz:epsilon, relative:T) returns True if all
differences d = x1 - x2 satisfiy abs(d) <= epsilon*(abs(x1)+abs(x2)).

@@@@chkxxxx_keywords#Keywords 'chkxxxx'
By default, equal() compares structure component names for equality but
ignores coordinate labels or attached notes.  You can change this
behavior by including any of 'chknames:F', 'chklabels:T' and
'chknotes:T' as arguments.

@@@@examples#Examples
Examples:
  Cmd> x1 <- .001*run(3); x2 <- x1 + 1e-10

  Cmd> equal(x1,x2) # exact equality test
  (1) F

  Cmd> equal(x1,x2,fuzz:1e-9) # absolute differences small enough
  (1) T

  Cmd> equal(x1,x2,fuzz:1e-9,relative:T) # relative difference too big
  (1) F

  Cmd> equal(asLong(run(3)), asLong(run(2,4)))
  (1) F

  Cmd> a <- run(3); b <- run(4); c <- vector(a,label:"A")

  Cmd> equal(a,b) # different shapes
  (1) F

  Cmd> equal(a,b,explain:T)
  component: equal
  (1) F
  component: reason
  (1) "Argument dimensions differ"

  Cmd> equal(a,c) # labels are ignorded by default
  (1) T

  Cmd> equal(a,c,chklabels:T,explain:T) # check labels for equality
  component: equal
  (1) F
  component: why
  (1) "Argument labels differ"

  Cmd> equal(structure(a,b),structure(c,b),explain:T)
  component: equal
  (1) F
  component: why
  (1) "Structure component [1] names differ"

  Cmd> equal(structure(a,b),structure(c,b),chknames:F)#ignore comp names
  (1) T

  Cmd> A <- structure(PI,structure(a)) # nested structures

  Cmd> B <- structure(PI,structure(b)) # nested structures

  Cmd> equal(A, B, explain:T) # compare nested structures
  component: equal
  (1) F
  component: why
  (1) "Structure component [2][1] dimensions differ"

In the last example, the explanation identifies the inequality as being
in structure component 1 of structure component 2 (A[2][1] differs from
B[2][1]).

@@@@see_also#Cross references
See also topics 'variables', 'arithmetic', 'logic', 'notes', 'labels',
structure(), 'structures'.

====error()#output
%%%%
error(a, b, ...[,format:Fmt or nsig:m, header:F, labels:F,
  missing:missStr, zero:zeroStr, macroname:F]), CHARACTER scalars Fmt,
  missStr and zeroStr, integer m > 0
%%%%
@@@@usage#Usage
error() is almost identical to print().  It differs in ways which make
it useful for reporting errors recognized in a macro.

(i) Use of error() immediately terminates execution of the current line
or macro.

(ii) error("Oops!") will print "ERROR: Oops!", where "Oops!" is a single
quoted string or CHARACTER scalar that does not start with "ERROR:" or
"WARNING:".  When the message starts with "ERROR:" or "WARNING:" error()
prints it unchanged.

(iii) In macro mymacro(), say, error("Oops!") prints
  "ERROR: Oops! in macro mymacro".

@@@@macroname_keyword#Keyword 'macroname'
To avoid appending the macro name when using error() in a macro, use
keyword phrase 'macroname:F'.  This is helpful when the error message
itself contains the macro name is in
   error("argument 2 to mymacro >= 1",macroname:F)

@@@@example#Example
Example:
  Cmd> for(i,run(nrows(x))){if(x[i] >= 0){y[i] <- sqrt(x[i]);;}else{
        error("attempt to take square root of number < 0")}}

This will terminate the loop on the first x[i] < 0.  The message printed
will actually be "ERROR: attempt to take square root of number < 0".

@@@@see_also#Cross references
See also topics print(), write(), paste(), 'macros', 'macro_syntax',
'for', 'if'.
@@@@______

====evaluate()#general,syntax,macros,control
%%%%
evaluate(cmds), cmds a quoted string or CHARACTER scalar.
%%%%
@@@@usage#Usage
evaluate(Cmds), where Cmds is a quoted string or CHARACTER scalar
consisting of one or more MacAnova commands, executes the commands and
returns the value of the last one.  Unlike macro expansion, symbols
starting with '$' in Cmds have no special significance.

As an argument to evaluate(), Cmds is called an "evaluated string".

@@@@example#Example
  Cmd> b <- evaluate("a <- PI;sqrt(a)");print(a,b)
  a:
  (1)       3.1416
  b:
  (1)       1.7725

In most situations, including the example just given, <<Cmds>> is
equivalent to evaluate(Cmds).  See topic 'syntax'.

@@@@limitations#Limitations
An evaluated string can contain any MacAnova commands except batch() and
quit() (and its synonyms; see topic 'quitting').  There are also
restrictions on the use of 'break', 'breakall', 'next' and 'return',

  'break' and 'next' can be used only to exit or skip to the end of a
  loop that was started in the evaluated string.

  'return' can be used only to exit a macro that was invoked in the
  evaluation string.  'return' cannot be used to exit from the
  evaluated string.

  'breakall' exits the outermost loop that started in the evaluated
  string.

@@@@recursive_use#Recursive use
You can use evaluate() recursively, in the sense that evaluate() can be
one of the commands in the evaluated string.  The depth D of such a
recursion must satisfy D <= 49 - M, where M is the number of out-of-line
macros currently being evaluated.  For example, because there are no
out-of-line macros in use (M = 0), the last value of i printed by

  Cmd> i <- 0; cmd <- "i <- i+1;print(i);evaluate(cmd)";evaluate(cmd)

will be 49, followed by an error message.

@@@@see_also#Cross references
See also topic 'macros'.
@@@@______

====exp()#transformations
%%%%
exp(x), x REAL or a structure with REAL components
%%%%
@@@@usage#Usage
exp(x) returns the exponential function (e^x) of the elements of x, when
x is a REAL scalar, vector, matrix or array.  The result has the same
shape as x.

@@@@missing_or_too_large_argument#Missing or too large argument
If any element of x is MISSING or > 709.782712893, the corresponding
element of exp(x) is MISSING and a warning message is printed.

@@@@structure_argument#Structure argument
When x is a structure, all of whose non-structure components are REAL,
exp(x) is a structure of the same shape and with the same component
names as x, with each non-structure component transformed by exp().

@@@@see_also#Cross references
See topic 'transformations' for more information on exp().
@@@@______

====factor()#glm,anova
%%%%
factor(n1 [, n2, ...]) where n1, n2, ... are REAL scalars or vectors,
  all of whose elements are positive integers.
%%%%
@@@@usage#Usage
factor(A), where A is a vector of positive integers or MISSING, creates
a vector with contents identical to A except that the new vector is
marked as a "factor" with number of factor levels = max(A).

The non-MISSING elements of A must be positive integers <= 32767.

Since the number of factor levels is the largest integer in A, both
factor(vector(1,2,4)) and factor(vector(1,2,3,4)) produce factors marked
as having four levels, although only three of the levels are present in
factor(vector(1,2,4)).

Argument A can also be a matrix or array when isvector(A) is True, that
is, when all dimensions beyond the first must be 1.  In that case the
result has the same dimensions as A.

factor(a1, a2, ... ak) is equivalent to factor(vector(a1, a2, ... ak))
where a1, ..., ak are all scalars or vectors.

@@@@logical_argument#Logical argument
When A is a LOGICAL vector, factor(A) is equivalent to factor(A+1), that
is, False and True are translated to levels 1 and 2, respectively.  The
result is always marked as having 2 factor levels, even if every element
of A is False.

@@@@purpose#Purpose
The purpose of marking a variable as a factor is to ensure that, when it
is a variable in a model for a non-regression GLM (generalized linear or
linear model) command such as anova() or poisson(), its values are
interpreted as specifying levels of a categorical (non-quantitative)
variable, that is, classes or categories.

A vector in a model that has not been marked as a factor using factor()
is called a "variate" and its values are taken to specify quantities,
even if they are all positive integers.  In regress(), and screen()
factors are treated the same as variates -- that is the levels are
viewed as quantitative.

In a model which includes both factors and variates, the variates are
often referred to as "covariates".

@@@@common_mistake#Common mistake
A common mistake in using GLM commands is to forget to use factor() to
turn vectors of factor levels into factors.  This error results in their
being treated as variates with single degrees of freedom.

@@@@subscripted_factor#Subscripted factor
When A is a factor with k levels and J is an appropriate subscript for A
(for example, J might be A != 3, vector(1,run(3,length(A))) or -2), A[J]
is also marked as a factor with k levels, even if max(A[J]) < k.

@@@@assignment_to_subscripted_factor#Assignment to subscripted factor
When A is a factor with k levels, A[j] <- newvalue is legal only if
newvalue is an integer between 1 and k.  The number of levels associated
with A will not change even if max(A) < k after the replacement.

@@@@maximum_level_less_than_nominal#Maximum level less than nominal
In both these last two situations, subscripting a factor or assigning to
a subscripted factor, it is possible to create a factor whose actual
maximum level is less than k.  However, the actual maximum factor level
will be used in any analysis.

@@@@see_also#Cross references
See also topics makefactor(), 'models'.
@@@@______

====fastanova()#glm,anova
%%%%
fastanova([Model] [,print:F or silent:T,fstats:T,pvals:T])
%%%%
@@@@usage#Usage
fastanova(Model) computes the analysis of variance table for the model
given in the CHARACTER variable Model.  No variates (only factors) can
be in the model.  It uses an iterative algorithm rather than the
modified Gram-Schmidt used by anova().

Caution:  If there are empty cells in the design, the degrees of freedom
and hence the mean squares may be in error.

fastanova(), with no Model specified, uses the model from the most
recent GLM command such as anova() or poisson() or the model in
STRMODEL.

@@@@keywords#Keywords
fastanova(Model,maxiter:N,epsilon:eps) where N is a positive integer and
eps is a small REAL scalar, iterates no more than N times (default is
25) on each fit and uses the value of eps (default is 1e-6) to determine
when convergence has occurred.  Either keyword can appear without the
other.

Other keyword phrases that can be used with fastanova() are 'print:T',
'silent:T', 'fstats:T' and 'pvals:T'.  See topic 'glm_keys' for details.
See topic 'options' for information on changing the default values of
'fstats' and 'pvals'.

Keyword phrases 'coefs:F' and 'marginal:T' cannot be used with
fastanova().

@@@@see_also#Cross references
See topic 'models' for information on specifying Model.
@@@@______

@@@@caveats#Caveats
Coefficients may be retrieved by coefs(); standard errors are not
available.

contrast() does not work properly after fastanova().  coefs() may or may
not give the correct answers; fastanova() will warn you when coefs()
will fail.  cellstats() results include the estimated values for any
missing data.

@@@@method_used#Method used
The iterative fitting method used by fastanova() is faster than Gram-
Schmidt for large unbalanced data sets.  The time used is roughly
proportional to length(y)*nterms, where y is the response variable, and
nterms is the number of terms in the model (the not the model degrees of
freedom).  Thus, fastanova() gives greatest speed improvements for
models with relatively few terms, each with relatively many degrees of
freedom.  fastanova() is least effective for models with many terms,
each with few degrees of freedom.  In fact, it may be slower than
anova() for such models.
@@@@______

====file_names%#files,input,output
%%%%
Type help(file_names) for information on file and path names, and the
  use of '~' and variable HOME to abbreviate file names.
Type help(DATAPATHS) for information on CHARACTER vector DATAPATHS and
  how it specifies where MacAnova searches for files.
Type help(files) for information on default directories and a little
  information on file formats
%%%%
@@@@introduction#Introduction
This topic summarizes information about the names of files recognized by
MacAnova, absolute and relative path names, and the use of '~' and
variable HOME in abbreviating file names.

See topic 'files' for information on the default directory or folder.

See topic 'DATAPATHS' for information on CHARACTER vector DATAPATHS and
how it specifies where MacAnova searches for files.

@@@@file_names
                               File names
You specify a file name by a quoted string or CHARACTER scalar (see
topic 'scalars') such as "macanova.dat".  It must be a legal file name
for your system.  When MacAnova decides it is not a legal name it prints
the message
   ERROR: improper file name xxxxxxx.

On some systems, the checks exclude some technically legal file names.
For example, in Unix/Linux, MacAnova objects to names starting with '-'
such as "-savefile" and on a Macintosh, it objects to file names
starting with '.' such as ".savefile", because their use often leads to
difficulties.

The DOS version does not recognize long file names.

@@@@empty_file_name
                        Use of "" as a file name
In versions with windows, you can always use the 'empty string' "" as
a file name.  This brings up a dialog box in which you can select a
folder and a file.  It also may change the default directory or folder. 
See topic 'files'.

@@@@path_names
                               Path names
If your file name includes directory or folder information, it is a
'path name' and can be relative or absolute.  In the next paragraphs,
for a Macintosh or Windows 95/98/NT, 'directory' should be taken to mean
'folder'.  This information is fairly technical.

@@@@path_names_relative
Relative paths
  Under DOS/Windows, Unix/Linux, and Mac OS X a file name that specifies
  a relative path might be "../data.dir/mydata" or 
  "tseries.dir/tseries.dat" (under Windows or DOS you could replace '/' 
  by '\\').

  On Mac OS 9, a relative path starts with ":".  Examples would be
  "::data.dir:mydata" and ":tseries.dir:tseries.dat".

  These examples specify a file 'mydata' in a directory 'data.dir' in
  the "parent" directory of the default directory, and a file
  'tseries.dat' in a sub-directory 'tseries.dir' in the default
  directory.

@@@@path_names_absolute
Absolute paths
  On Unix/Linux and Mac OS X, "/usr/lib/macanova/survey.dat" is a 
  typical absolute path name.  It must start with '/'.

  On Windows and DOS an absolute path name starts with '/' or 'X:/'
  where 'X' is a designator such as 'A' or 'C' of a disk drive.  For
  example, if the current DOS default drive is drive 'C', both
  "C:/data.dir/survey.dat" and "/data.dir/survey.dat" specify the same
  file.

  On Mac OS 9, an absolute path name starts with a disk name and
  contains at least one ":".  Example: "MyFloppy:data.dir:survey.dat".

@@@@use_of_HOME_and_tilde
               Use of '~' in file names and variable HOME
You may be able to use an abbreviated file name like "~/Name" or 
"~:Name" (Mac OS 9), where "Name" is the name of a file.  For this to
work, a CHARACTER scalar HOME must exist and contain the complete name
(absolute path) of a directory.  For example, in Windows if HOME is 
"C:/SURVEY", the "~/mydata.dat" becomes "C:/SURVEY/mydata.dat". On 
Mac OS 9, when HOME is "MyFloppy:Survey", "~:mydata.dat" becomes 
"MyFloppy:Survey:mydata.dat".

On Unix/Linux, Mac OS X, and most versions of Windows, HOME is
predefined to be the user's home directory (for example, /hom/gary
or /Users/gary or c:/Documents and Settings/gary).  On DOS, HOME 
is pre-defined to be the full name of the directory where the 
executable MacAnova program is located.  You can override the default
for HOME using command line option -home.  See topics 'launching'
and 'customize'.

On Unix/Linux computers, a file name of the form ~name/filename, where
name is the log in name of another user, ~name is translated to the name
of that user's home directory, following a convention used in the csh
shell.

====files%#files,input,output,missing values
%%%%
Type help(files) for information on default directories or folders and
  general information on file formats.
Type help(file_names) for information on file names, directories or
  folders that are searched and CHARACTER vector DATAPATHS
Type help(data_files) for general information on data files MacAnova can
  read.
Type help(matread_file) for information on the format of files readable
  by matread() and read().
Type help(vecread_file) for information on the format of files readable
  by vecread() and readcols().
Type help(macro_files) for information on the format of files readable
  by macroread() and read().
%%%%
@@@@introduction#Introduction
This topic describes some aspects of the use of files.  Much of it is
fairly technical and not of great interest to the casual user.  It has
sections on default directories or folders and a little information on
file format.  See topics 'file_names', 'data_files', matread_file',
'vecread_file' and 'macro_files' for information on file names and
descriptions of formats for data files and macro files.  See topic
'file_names' for information on specifying file names.

@@@@default_directories
                     Default directories or folders
Generally MacAnova first looks for the named file in the default
directory or folder, unless the supplied file name is a "path" name,
specifying a directory or folder and a file.  If MacAnova does not find 
the file in the current directory, it then looks in the directories or
folders in CHARACTER vector DATAPATHS.  See topic 'DATAPATHS'.

If you start MacAnova from the command line, then the initial default
directory is the current directory at the command line (on DOS, this might
be different if MacAnova is started by a *.BAT file that includes a CD
command).

@@@@changing_default_directory
                     Changing the default directory
On command line versions of MacAnova, you cannot change the default
directory after startup.

In the windowed versions of MacAnova, the default directory is changed
whenever you use the file navigation dialog box to select a file in a
different folder or directory.  Thus the first time you read a file from
a given folder, you should use "" as file name.  If you want, you can
then read other files in the same folder by specifying their names.

@@@@file_formats
                              File formats
On all systems, data, macro, batch, and window files must be plain text
(ASCII) files.  These files often have a .txt extension.  If you create
them using a word processor, be sure to specify plain text format when
you save them.  On any system, MacAnova can correctly read text files
from all other systems (i.e., with Windows/DOS, Macintosh or Unix/Linux
line separating codes).  See topic 'data_files'.

See topics 'vecread_file' and 'matread_file' for information on how data
should be organized in files to be read by vecread() and read() or
matread(), respectively.

See topic 'macro_files' for information on the format of files to be
read by macroread().

See batch() for information on the format of batch files.

Files written by asciisave() are ASCII files but are not meant to be
read or edited by humans, and their format is arcane and subject to
change.  The asciisave() format is the same across computer types, so
that, for example, a DOS machine can read a Macintosh asciisave() file
and vice versa.  asciisave() files can also be emailed as is, without
encoding.

Files written by save() are binary files with formats that may differ
among computer types, but most can be read on all systems.

@@@@help_files#Help files
The default help file, usually "Macanova.hlp.txt" in the SharedSupport
directory below the MacAnova application, is a text file in a special
format.  The format is described near the start of the file.  If you
develop a file of macros, you could use this information to write a
special help file.  Or a macro file can be its own help file if you put
the properly formatted help after a line starting
_E_N_D_O_F_M_A_C_R_O_S_.  See topic 'macro_files'.

The help command will automatically search all the files whose names are
in pre-defined CHARACTER vector HELPFILES.  You can use addhelpfile() to
add a file name to HELPFILES.

Internally, help uses gethelp() and keywords 'file', 'orig' and 'alt'
to switch among files.

See help(), gethelp(), arimahelp(), designhelp(), graphicshelp(),
mathhelp(), mulvarhelp(), regresshelp(), tserhelp() and addhelpfile().

@@@@______

====findfile()#files
%%%%
findfile(filename), filename a CHARACTER scalar
%%%%
findfile(filename) returns a path to the requested file, or NULL if the
file cannot be found.  Searching is done based on the paths in
DATAPATHS.  First, findfile() looks for ./filename (the current
directory), then DATAPATHS[1]/filename, DATAPATHS[2]/filename, and
so on.  findfile() returns a path to the first matching file.  Paths
may be relative or absolute depending on DATAPATHS.

====floor()#transformations
%%%%
floor(x), x REAL or a structure with REAL components
%%%%
@@@@usage#Usage
floor(x) rounds the elements of the REAL variable x to the next integer
in the negative direction, producing a vector, matrix, or array with the
same shape as x.

Example:
  Cmd> floor(vector(3.1416, -3.1416, 12))
  (1)           3          -4          12

@@@@too_large_arguments#Too large arguments
When x > 4503599627370495 or x < -4503599627370495, floor(x) is set to
MISSING because of the impossibility of exact representation of integers
beyond these limits.  These limits may be different on some computers.

@@@@structure_argument#Structure argument
If x is a structure, so is floor(x).  If xi is the i-th component of x,
the i-th component of floor(x) is floor(xi).

@@@@see_also#Cross references
See also topics ceiling(), round(), 'structures'.
@@@@______

====for#syntax,control
%%%%
for(i,vec)){command1;command2; ...}, vec a REAL vector
for(i,start,end [, incr]){command1;command2;...}, start, end and incr
  REAL scalars
for(i,NULL){...}
%%%%
@@@@usage#Usage
for(Index,Range){statement1;statement2;... } where Range is a REAL
vector of length N repeats the statements in {...} N times with Index
successively taking the values Range[1], Range[2], ..., Range[N].

Unless the last statement in {...} is NULL (';;') its value may be
printed on each loop.  The most common form for Range is 'run(n)' which
results in the statements in {...} being repeated n times, with variable
Index taking values 1, 2, ..., n.

for(Index,NULL){...} skips the compound statement {...} entirely.  An
example might be
  Cmd> for(i, run(length(x))[x>10]){print(paste("x[",i,"] > 10"))}
when max(x) < 10.  In this case run(length(x))[x>10] is NULL.  See
topics 'subscripts' and 'NULL'.

for(Index,i1,i2){...} is equivalent to for(Index,run(i1,i2)){...}.

for(Index,i1,i2,incr){...} is equivalent to for(Index,
run(i1,i2,incr)){...}.

@@@@value#Value
A 'for' statement does not have a value.  Hence such constructs as
  yyy <- for(i,run(3)){i+2} or 4 + for(i,run(3)){i+2}
are illegal.

@@@@early_termination#Early termination
You can terminate a "for loop" prematurely using syntax elements 'break'
and 'breakall' or pre-defined macro breakif().

You can skip to the end of a "for loop" using syntax element 'next'.

@@@@examples#Examples
Example:
  Cmd> @n <- length(a);@s <- 0;for(i,run(@n)){@s <- @s+(a[i]-1)^2;;}; @s
is essentially equivalent to sum((vector(a)-1)^2).  'for(i,run(@n))'
could be replaced by 'for(i,1,@n)' or 'for(i,1,@n,1)'.

The following might be better:
  Cmd> @s <- 0; for(@ai,vector(a)){@s <- @s + (@ai - 1)^2;;}; @s

The opening '{' after 'for(...)' must be on the same line as 'for'.

@@@@see_also#Cross references
See also topics 'while', 'break', 'breakall', breakif(), 'next'.
@@@@______

====fprint()#output,files
%%%%
fprint(fileName, a, b, ...[,format:Fmt or nsig:m, header:F, labels:F,\
  missing:missStr, height:h, width:w]), Fmt, missStr, fileName CHARACTER
  scalars, m > 0, h >= 12 integer, w >= 30 integer
%%%%
@@@@usage#Usage
fprint(name,a,b,...) is equivalent to print(a, b, ...,file:name).  The
use of fprint() is discouraged.  Use print(a, b, ..., file:name)
instead.

See print() and write() for details on keyword use.

@@@@see_also#Cross references
See also write(), matprint(), matwrite(), macrowrite().
@@@@______

====formatpval()#output
%%%%
result <- formatpval(pvals [,minpval:minp] [,format:fmt]), non-negative
  REAL vector or scalar, nonnegative REAL scalar minp <= .001, CHARACTER
  scalar fmt
%%%%
@@@@usage#Usage
formatpval() is designed to be used in a macro to format printed
P-values similarly to the way the built-in GLM functions such as
regress(), anova() and logistic() do.

result <- formatpval(pvals), where pvals is a REAL scalar or vector with
min(pvals) >= 0, computes the CHARACTER scalar or vector result the same
length as pvals.

If pvals[i] < minP, where minP is the value of option 'minpval', then
result[i] has the form, for example, "< 1e-8", when minP = 1e-8.  If
pvals[i] >= minP, result[i] is simply paste(pvals[i]).

result <- formatpval(pvals, minpval:minP), where 0 <= minP <= .001 does
the same, except the supplied value of minP is used.

result <- formatpval(pvals, format:fmt [, minpval:minP]), where fmt is a
CHARACTER scalar specifying a legal output format (see subtopic
options:"format"), does the same, except fmt is used to format result,
instead of the default format.

@@@@example#Example
  Cmd> tstats <- vector(4.585, 5.536, 6.576, 7.611, 8.826)

  Cmd> formatpval(twotailt(tstats,23),minpval:1e-7,format:".3g")
  (1) "0.000131"
  (2) "1.25e-05"
  (3) "1.04e-06"
  (4) "< 1e-07"
  (5) "< 1e-07"

@@@@see_also#Cross references
See also print(), write(), options:"minpval", options:"format",
twotailt().

====fromclip()#character variables,input
%%%%
fromclip([ncol]), ncol > 0 an integer
%%%%
@@@@usage#Usage
y <- fromclip() does a vecread() from CLIPBOARD, creating a REAL vector
y.

y <- fromclip(ncol) is equivalent to matrix(fromclip(),ncol)', where
ncol is an integer.  This creates a REAL matrix with ncol columns and
makes most sense if the contents of CLIPBOARD are arranged in ncol
columns as they would be after CLIPBOARD <- x, where x is a matrix with
ncol columns.

@@@@importing_data_in_windowed_versions#Importing data in windowed versions
In windowed versions, fromclip() allows easy importing of data from
other applications such as a spreadsheet. For example, if you have
Copied to the Clipboard a 10 by 5 rectangle of spreadsheet cells
containing numbers, or 10 lines of a 5 column numerical table in a word
processor or editor,
   x <- fromclip(5)
will create a 10 by 5 REAL matrix consisting of the data copied.
@@@@______

fromclip() is implemented as a pre-defined macro.

@@@@see_also#Cross references
See also topic clipreaddata().
@@@@______

====fwrite()#output,files
%%%%
fwrite(fileName, a, b, ...[,format:Fmt or nsig:m, header:F, labels:F,\
  missing:missStr, width:w, height:h]), Fmt, missStr, fileName CHARACTER
  scalars, m > 0, w >= 30, h >= 12 integers
%%%%
@@@@usage#Usage
fwrite(name,a,b,...) is equivalent to write(a, b, ..., file:name).  The
use of fwrite() is discouraged.  Use write() instead.

See write() and print() for details on keyword use.

@@@@see_also#Cross references
See also matprint(), macroprint().
@@@@______

====getascii()#character variables
%%%%
getascii(charVec1 [, charVec2 ...]), all arguments CHARACTER vectors
%%%%
@@@@usage#Usage
getascii(c), where c is a CHARACTER scalar or quoted string, returns a
REAL vector with integer elements between 1 and 255 inclusive which are
the ASCII codes corresponding to the characters in c.  If c is the null
string "", getascii(c) returns NULL (see 'NULL').

getascii(c1, c2 [, c3 ...]), where all the arguments are CHARACTER
vectors, is equivalent to getascii(paste(c1,c2,..., sep:"")), collapsing
all the elements of all the arguments into one CHARACTER scalar before
decoding.  See paste().

getascii(c) is almost an inverse function to putascii(x,keep:T) in the
sense that getascii(putascii(x,keep:T)) returns x when x is a REAL
vector with integer elements between 1 and 255, and
putascii(getascii(c),keep:T) returns c when CHARACTER scalar c != "".

@@@@examples#Examples
Examples:
  Cmd> getascii("ABCDE") # ascii code of 'A' is 65, etc.
  (1)           65           66           67           68           69

  Cmd> getascii(vector("AB","C"), "DE") # same as preceding
  (1)           65           66           67           68           69

  Cmd> getascii("\001\002\003\004\005") #or getascii("\1\2\3\4\5")
  (1)            1            2            3            4            5

  Cmd> getascii("\x01\x02\x03\x04\x05") # same as preceding
  (1)            1            2            3            4            5

  Cmd> getascii(putascii(run(30,34),keep:T))
  (1)           30           31           32           33           34

  Cmd> putascii(getascii("MacAnova"),keep:T)
  (1) "MacAnova"

@@@@see_also#Cross references
See also putascii().
@@@@______

====getdata()#files,variables,input
%%%%
y <- getdata(setName), where setName is the unquoted or quoted name of a
  data set in the file whose name is in variable DATAFILE
%%%%
@@@@usage#Usage
getdata() is a pre-defined macro to retrieve named data sets from a file
whose name is in CHARACTER scalar DATAFILE.  Specifically,
    y <- getdata(DataName)
is equivalent to
    y <- read(DATAFILE,"DataName")

The data set name optionally may be a quoted string, but may not be a
CHARACTER variable.

The file whose name is in DATAFILE must be in the form readable by
read() and matread().  See read(), matread() and topic 'matread_file'.

y <- getdata(DataName,quiet:T) suppresses the printing of any
descriptive comments associated with the data set in the file.

@@@@data_set_name#Data set name
The data set name dataName need not be a legal MacAnova variable name
since the name of a data set on a file readable by read() and matread()
can include characters such as '.' that are not legal in MacAnova
variable names.  For example, 'y <- getdata(jw11.5)' is legal and will
attempt to retrieve data set "jw11.5" from DATAFILE.

@@@@variable_DATAFILE#Variable DATAFILE
Variable DATAFILE is normally pre-defined to contain "macanova.dat", the
name of a sample file with several data sets.  On some systems DATAFILE
may be pre-defined to be some standard collection of data.  After

  Cmd> DATAFILE <- "disease.dat" # or other file name

getdata() will retrieve data sets from file disease.dat.

If the value of DATAFILE is a pure file name ("disease.dat" but not,
say, "data/disease.dat"), MacAnova will first search in the current
default directory or folder and then look in the directories or folders
whose names are in CHARACTER vector DATAPATHS.  See topics 'DATAPATHS'
and 'file_names'.

@@@@initializing_in_startup_file#Initializing in startup file
If you regularly use a particular data file, say, "mydata.txt", you
might find it convenient to add the line DATAFILE <- "mydata.txt" to
your startup file.  Or, on Unix/Linux, Windows and DOS, you can include
'-d mydata.txt' in environmental variable MACANOVA.  See topics
'customize' and 'launching'.

@@@@convention#A useful convention
A useful convention is to have the first dataset on the file have name
'info' and 0 lines (first header line 'info 0', with several comment
lines starting with ')' listing the datasets available in the file.
Then getdata(info) or even just getdata() will print this information.
See topic 'matread_file' for an example.
@@@@______

====getfilename()#files,input,output
%%%%
name <- getfilename([cancelok:T])
name <- getfilename(type:"data" or type:"restore" [,cancelok:T])
name <- getfilename(fileonly:T ...[,cancelok:T])
name <- getfilename(pathonly:T ...[,cancelok:T])
name <- getfilename(help:T [,fileonly:T  or  pathonly:T])
name <- getfilename(last:T [,fileonly:T  or  pathonly:T])
%%%%
@@@@usage#Usage
On windowed versions 

  Cmd> fileName <- getfilename()

brings up a file navigation dialog box in which you can select a file;
the complete path name (file name with directory information) of the
file is saved as a CHARACTER scalar in fileName.  It is an error if the
dialog box is cancelled without selecting a file.

  Cmd> fileName <- getfilename(cancelok:T)

does the same except it is not an error when the dialog box is cancelled
without selecting a file.  It that case, fileName is set to NULL.

There are two usages that are available on any version

  Cmd> fileName <- getfilename(help:T)

returns the name of the current help file.

  Cmd> fileName <- getfilename(last:T)

returns the name of the last file successfully opened by any MacAnova
command, either for reading or for writing.

@@@@keywords#Keywords
fileName <- getfilename(nameonly:T [,last:T or help:T] [,cancelok:T])
does the same, but only the name of the file, excluding the directory
information (path), is returned.

pathName <- getfilename(pathonly:T [,last:T or help:T] [,cancelok:T])
does the same, but only the directory information is returned.

It is an error to use both nameonly:T and pathonly:T as arguments.

On a Mac OS 9, without last:T or help:T, the files displayed in the
file navigation dialog box are limited to text files such as data files
and workspace files created by save().  To further restrict the files
displayed to text files, include keyword phrase type:"text" as an
argument.  Keyword 'type' can be used with 'nameonly:T' and
'pathonly:T'.  It has no effect in non-Macintosh versions.

@@@@when_to_use#When to use
One use for getfilename() is as an argument to macro addmacrofile():

  Cmd> addmacrofile(getfilename())

allows you interactively to choose a file to be added to the list of
macro files to be searched.

A similar use is as an argument to adddatapath():

  Cmd> adddatapath(getfilename(pathonly:T))

adds to variable DATAPATHS the name of the folder or directory
containing the file selected.  DATAPATHS contains a list of directories
that are searched when a file is not found in the current default
directory.

A use for 'help:T' might be in a macro searching several help files to
enable it to restore the current help file when it was done.

A use for 'last:T' might be in a macro which uses vecread() with
'silent:T' and you want to retrieve the name of the file read.

The following macro fragment should do that:
  @filename <- argvalue($1,"file name","string")
  @x <- vecread(@filename, silent:T)
  print(paste("Reading data from file",getfilename(last:T)))
  . . . .

See topics 'macros' and 'macro_syntax' for information on writing
macros.

@@@@______

====gethelp()#general,files
%%%%
gethelp([Topic1,Topic2,...] [,file:FileName or orig:T or alt:T]\
  [,scrollback:T, usage:T, silent:T, printname:T])
gethelp(Topic1:Subtopic1 [,Topic2:Subtopic2,...] [,other keywords]),
  Topic1, Topic2 ...  names of topics, Subtopic1, Subtopic2, ...,
  CHARACTER scalars or vectors
gethelp(Topic, subtopic:Subtopics [,other keywords])
gethelp(Topic, subtopic:"?" [,other keywords])
gethelp(Pattern [keywords]) where Pattern has form "start*",
  "start*end", or "*mid*", "start*mid*", ...
gethelp(key:KeyName [keywords]), where KeyName is a CHARACTER scalar or
  "?"
gethelp(news), gethelp(news:yymmdd1) or gethelp(news:vector(yymmdd1, \
  yymmdd2)), where yymmdd1 and yymmdd2 are integers like 990103,
  19990103, 000717 or 20000727
%%%%
@@@@introduction#Introduction
gethelp() retrieves help information from a "help file", a text file
in a special format.  It can be used directly, but is usually accessed
by macros help() or usage() which enable searching several files for
information.

gethelp() searches only the "current" help file.  This is initially
"macanova.hlp" but can be changed by keywords 'file', 'alt' and 'orig'
or by macros help() and usage().

@@@@usage#Usage
gethelp() with no argument prints a short message giving some of the
help() and gethelp() options.

gethelp("*") lists all help topics in the current help file.  There are
over 350 topics in the default help file, macanova.hlp, so this can be a
long list.

gethelp(Topic) prints information about the named topic.  The topic name
may be unquoted (gethelp(break)) or quoted (gethelp("break")).  Only the
current help file is searched.

gethelp(Topic, usage:T) does the same, except it gives only a brief
summary of how a command is used, without lengthy details or
explanation.  This is the same information as is provided by usage() and
getusage().  In fact, gethelp(Topic, usage:T) is equivalent to
getusage(Topic).

gethelp(topic, silent:T [,usage:T]) does the same, except any warning
messages are suppressed.  silent:T does *not* suppress printing of
help or usage information.

gethelp() returns an "invisible" LOGICAL scalar whose value is True only
when at least one topic requested was found.  The value may be assigned
or tested but will not be printed automatically.

  Cmd> if (!gethelp(topic)){print("No help found")}

See topic 'variables:"invisible"'.

@@@@subtopics#Subtopics
Most help topics are divided into subtopics that can be accessed
individually if you know what they are.  Common subtopic names are
"usage" and "example".

gethelp(Topic, subtopic:"?") lists all subtopic names, if any,
associated with Topic.  When the topic name is no longer than 10
characters, gethelp(Topic:"?") does the same.

gethelp(Topic, subtopic:Subtopics), where Subtopics is a quoted string
or CHARACTER vector gives help only on the subtopic or subtopics named
in Subtopics.  Upper and lower case is ignored in these names and all
subtopics starting with any name in Subtopics will be listed.  In the
most common case, Subtopic is a quoted string.  No other topics can be
arguments.  When the topic name is no longer than 10 characters,
gethelp(Topic:Subtopics) does the same.

@@@@examples#Examples
Examples:
  Cmd> gethelp(anova); gethelp(macros); gethelp("break")
  Cmd> gethelp(break) #nows work; previously didn't
  Cmd> gethelp(transformations) #now works; previously didn't
  Cmd> gethelp(regress, usage:T) # same as usage(regress)
  Cmd> gethelp(anova, subtopic:"example") # or gethelp(anova:"example")
  Cmd> gethelp(regress:vector("usage","example"))
  Cmd> gethelp(transformations,subtopic:"?")
  Cmd> if (!gethelp(foo,silent:T)){print("No help on topic foo")}
@@@@______

See macrousage() for a way to get usage information on currently defined
macros.

See below for using keywords 'file', 'orig' and 'alt' to control the
file from which gethelp() gets information.

@@@@scrollback#Keyword 'scrollback'
gethelp(Topic, scrollback:T) is legal only on a windowed version.
It causes the gethelp() output to be automatically scrolled back to
its start.  You can make this the default behavior by
setoptions(scrollback:T).  See topics setoptions(), 'options'
@@@@______

On windowed versions, the Help on the Help menu brings up a browser
(web/html) based version of the standard MacAnova help.  It does NOT
search the standard help files.  If you select a command name or other
topic name in the command window with the mouse, menu item Help gives
you help on that topic.  

@@@@key_for_finding_topics#Keyword 'key' to find topic names
gethelp(key:"foo") lists all topic names associated with key "foo".
Examples of keys are "Residuals", "Missing Values", "ANOVA", and
"Variables".  In matching keys, case (upper or lower) is ignored.
Moreover, you need type only enough letters to identify a key uniquely.
For example, gethelp(key:"resid") gives the same output as
gethelp(key:"Residuals").

gethelp(key:"?") lists all recognized keys.
@@@@______

You can also use one of keywords 'file', 'orig', or 'alt' (see below)
with 'key'.

@@@@wild_card_characters#Wild card characters
When you aren't sure of the exact topic name, you can use the "wild
card" characters '*' and '?' in a quoted string to define a pattern to
be matched.  '*' will match any 0 or more successive letters in a topic
name and '?'  matches any single letter.  All matching names are
printed.  If only one name matches, full help will be given on that
topic.
@@@@______

@@@@examples_of_wild_card_use#Examples of wild card use
Examples:
  gethelp("res*")     lists all topic names beginning with "res"
  gethelp("*line*")   lists all topic names containing "line"
  gethelp("*anova")   lists anova,fastanova, manova, wtanova, wtmanova
  gethelp("*plot")    lists names ending in "plot" like chplot(),
                      boxplot()
  gethelp("*pl?t")    lists all topic names whose last 4 characters or
                      "p", "l", any character, and "t" repectively
                      (plot(), lineplot() and split(), for example).
  gethelp("*tat*")    lists cellstats(), rotate(), rotation()
  gethelp("add*lin*") gives help for addlines() (only 1 matching)
  gethelp("*i*e*t")   lists all topic names containing "i" and "e", in
                      that order, and ending with "t" ('assignment' and
                      lineplot(), for example).
@@@@______

@@@@multiple_topics#Multiple topics
gethelp(Topic1,Topic2,... [,scrollback:T or usage:T] [,silent:T]) prints
information about each of the topics specified by the arguments.  If an
argument is a quoted string containing '*' or '?', it is used as a
pattern as above, but if there is more than one topic, only the first
topic in the help file whose name matches is printed.  The same rules
concerning quotes apply as when there is only one topic.

gethelp(Topic1:Subtopics1, Topic2:Subtopics2 [,...]) prints information
in the designated subtopics of Topic1, Topic2, ... .  You can also mix
in ordinary topic names without subtopics.

You can't name more than one topic when you use keyword 'subtopic'.

@@@@examples_of_multiple_topics#Examples of multiple topics
  gethelp(help,break) will produce this text and information about
                     syntax element 'break'
  gethelp(anova:vector("usage","examples"),option:"scrollback")
                     will print two subtopics to topic 'anova'
                     and one subtopic of topic 'option'

@@@@default_help_file#Default help file
The help information is kept in a file in a particular format.  The
default file name is macanova.hlp.  A description of the format is near
the start of the macanova.hlp

The actual file used can be changed using keyword 'file' or restored to
the default by keyword phrase 'orig:T'.  You can retrieve the name of
the actual current help file by getfilename(help:T).

Macros help() and usage() may change the current help file.  By default,
if the current help file contains the wanted topic, or if the topic is
not found in any help file, the current help file is not changed.  If
the topic is found in another file, that file becomes the current help
file.

@@@@news_topic
                              Topic 'news'
gethelp(news [,scrollback:T]) lists in reverse chronological order news
items about MacAnova starting with the most recent entry back for three
months.

gethelp(news:vector(Date1,Date2) [,scrollback:T]), where Date1 and Date2
are numbers of the form yymmdd or yyyymmdd, lists in reverse
chronological order news items about MacAnova development dated between
Date1 and Date2.  For example, gethelp(news:vector(991201,0000131)) and
gethelp(news:vector(19991201,20001230)) list all news items dated in
December, 1999 or January, 2000

gethelp(news:Date) lists all news items on or after Date.  For example,
gethelp(news:000101) and gethelp(news:200000100) list all news items on
or after January 1, 2000.

gethelp(news:0) lists all available news items.  This will produce many
of lines of output and is not recommended.

@@@@other_help_files
                         Using other help files
Currently there are ten files distributed with MacAnova which contain
help.  Some also contain the macros they provide help for.

   File                     Contents
  ----------------------------------------------------------------------
  arima.mac             Help on macros in arima.mac
  design.hlp            Help on the macros in file design.mac
  graphics.mac          Help on macros in graphics.mac
  macanova.hlp          Help on all MacAnova commands, predefined macros
                        and general information (the default help file)
  macanova.nws          Old news items and obsolete help topics removed
                        from macanova.hlp
  math.mac              Help on macros in math.mac
  mulvar.mac            Help on macros in mulvar.mac
  regress.mac           Help on macros in regress.mac
  tser.hlp              Help on the macros in file tser.mac
  userfun.hlp           Help related to programming user functions

On a single call, gethelp() scans only a single file for help.  The
default help file is macanova.hlp.

Predefined macro help() uses gethelp() to scan all files whose names are
in CHARACTER variable HELPFILES until it finds help on a requested
topic.  The default value of HELPFILES contains all the above files
except macanova.nws and userfun.hlp.  help() is used almost identically
to gethelp().

If you know which file the topic is, you can use one of the pre-defined
macros arimahelp(), designhelp(), graphicshelp(), mathhelp(),
mulvarhelp(), regresshelp(), tserhelp() and userfunhelp() for easy
retrieval of help from the other files (except macanova.nws).  These are
used essentially the same way as help().  See topics arimahelp(),
designhelp(), graphicshelp(), mathhelp(), mulvarhelp(), regresshelp(),
tserhelp() and userfunhelp() for details.  The may have an advantage
over help() in that they scan only one file.

Or you can use gethelp() with keyword 'file'.  See below.

@@@@examples_for_help_macros#Examples for help macros
  arimahelp("*")           lists all topics in file arima.mac
  designhelp(aliases2)     prints help information on macro aliases2()
                           in design.mac
  mathhelp(i0,usage:T)     prints usage on macro i0() in math.mac
  regresshelp(key:"anova") lists topics related to key 'anova' in file
                           regress.mac

These macros make use of keywords 'file', 'orig' and 'alt' that direct
gethelp() to change help files.

@@@@file_orig_and_alt_keywords#Keywords 'file', 'orig' and 'alt'
gethelp(file:FileName) where FileName is a quoted string or CHARACTER
variable specifying the name of a file, makes that file an alternate
help file and switches over to using it.  In versions with windows,
when FileName is "", you use a dialog box to select the file.  One or
more topic names can follow file:FileName or file:FileName can be the
last argument.  The alternate help file remains active until another is
specified, or keyword phrase orig:T appears in a gethelp() command. 
If the file is not in the correct format for a help file, the results
are unpredictable but not pleasant.

gethelp(orig:T) restores the help file to what it was at startup.  This
will either be the standard help file or the one specified (under
Unix/Linux or DOS) by the -h option on the command line.  See topic
'launching'.  One or more topic names can follow orig:T, or orig:T can
be the last argument.

gethelp(alt:T) restores the help file to the one most recently specified
by file:fileName.  It is an error if no alternative file was previously
set.  This allows you easily to use two help files, the default one and
one alternate.  You switch back and forth between them by
gethelp(orig:T) and gethelp(alt:T).  One or more topic names can follow
alt:T, or alt:T can be the last argument.

@@@@historical_notes#Historical notes
Prior to Version 4.12, gethelp() was named help().  help() is now a
macro that uses gethelp() to search several help files.  If you want
help() to work identically to gethelp(), you can define a simplified
version by:
  Cmd> help <- macro("gethelp($0)")

Prior to Version 4.11, topics longer than 12 characters or that were
control words ('if', 'while', 'for', 'else', 'elseif', 'break',
'breakall') had to be quoted.  This is no longer the case.

@@@@______

Help() is a synonym for gethelp() and is used identically.

====gethistory()#general
%%%%
gethistory(n) where n > 0 is an integer
gethistory()
%%%%
@@@@usage#Usage
gethistory(n), where n is a positive integer, returns a CHARACTER vector
containing up to n previous commands in the order they were executed.

gethistory(), with no argument, returns a CHARACTER vector containing
all available previous commands.

At most nHist - 1 commands are returned, where nHist is the value of
option 'history'.  See topic 'options'.

If there are no previous commands available, both gethistory(n) and
gethistory() return "".

See sethistory() for information on how to replace the current internal
list of previous commands.

gethistory() is not implemented in the limited memory DOS version or in
any version that does not allow keyboard or menu retrieval of previous
commands.
@@@@______

====getkeywords()#syntax,macros
%%%%
getkeywords(arg1 [,arg2, arg3 ...]), arg1, arg2, ... arbitrary.
%%%%
@@@@usage#Usage
result <- getkeywords(arg1 [, arg2, ..., argK]) returns a CHARACTER
vector of length K.  If argument i is a keyword phrase, result[i] is the
keyword name; otherwise result[i] is "".

  Cmd> getkeywords(cos:3, kappa:PI,a,"b",3)
  (1) "cos"
  (2) "kappa"
  (3) ""
  (4) ""
  (5) ""

@@@@use_in_macro#Use in macro
The principal use for getkeywords() is in a macro.  It is one of the
tools for analyzing the argument list to a macro.  For example, it is
sometimes necessary to identify which arguments are keyword phrases and
which are not.

Here is a snippet of code that might be in a macro.

  @keynames <- getkeywords($0) # check entire argument list
  @keynames <- @keynames[!ismissing(@keynames)] # extract keyword names
  if (!isnull(@keynames)){
    @legalkeys <- vector("short","long","narrow","wide")
    for (@i,1,length(@keynames)){
      if (match(@keynames[@i], @legalkeys, 0) == 0) {
        error(paste(@keynames[@i],"is not a legal keyword"))
      }
    }
  }

This checks to see that all keywords in the argument list are in a list
of permissible keyword names.

@@@@see_also#Cross references
See also argvalue(), keyvalue(), 'keywords', 'macro_syntax', 'macros',
match().
@@@@______

====getlabels()#general,variables
%%%%
getlabels(x [,silent:T,trim:F]) or getlabels(x,dims [,silent:T,trim:F]),
  dims a vector of positive integers
%%%%
@@@@usage#Usage
getlabels(x) returns the coordinate labels assocated with variable x.
When x is a structure or ndims(x) = 1, the result is a CHARACTER vector
of length ncomps(x) or dim(x)[1] or a CHARACTER scalar; otherwise the
result is a structure with ndims(x) components, each of which a
CHARACTER vector of length dim(x)[i] or a CHARACTER scalar.

A scalar is returned for a coordinate label only if all the labels for
that coordinate are identical and either are "" or start with "@", in
which case the first label is returned.  Effectively, non-essential
elements are trimmed from a vector of labels.

getlabels(x, dims), where dims is a vector of positive integers, returns
the labels associated with coordinates dims[1], dims[2], ... of x in the
same form as for getlabels(x).  If length(dims) = 1, the result is a
CHARACTER scalar or vector; otherwise it is a structure of CHARACTER
scalars or vectors.

For both usages, when x has no labels, a warning message is printed and
NULL is returned.  See topic 'NULL'.

@@@@trim_and_silent_keywords#Keywords 'trim' and 'silent'
getlabels(x [, dims], trim:F) forces the complete labels for each
requested dimension to be returned without trimming of non-essential
elements.

getlabels(x [, dims], silent:T) suppresses the warning message if there
are no labels.

You can determine whether a variable has labels by
  Cmd> if (!isnull(getlabels(x,silent:T))){...do something...}

@@@@see_also#Cross references
See also topics 'labels', haslabels(), addmacrofile(), adddatapath().
@@@@______

====getmacros()#macros,files,input
%%%%
getmacros(name1 [,name2 ... ] [,quiet:T, silent:T, printname:F]), name1,
  name2 ... quoted or unquoted macro names to be read from one of files
  named in CHARACTER vector MACROFILES
%%%%
@@@@usage#Usage
getmacros(Macro1,Macro2,...) retrieves macros Macro1, Macro2, ... from
one of the files whose names are in pre-defined CHARACTER vector
MACROFILES.  The macro names may be quoted (getmacros("mymacro")) or
unquoted (getmacros(mymacro)), but may not be CHARACTER variables.

By default, getmacros() prints the name of the file from each macro is
read.

getmacros(Macro1,Macro2,...,quiet:T) retrieves the macros but suppresses
printing the descriptive comments associated with them.

getmacros(Macro1,Macro2,...,printname:F [,quiet:T]) does the same, but
the file name or names are not printed.

If there is more than one copy of any of the named macros in the files
named in MACROFILES, getmacros() retrieves the first one found.  The
files of macros are searched in the order they are in MACROFILES.

@@@@default_macro_files#Default macro files
MACROFILES is predefined with value vector("graphics.mac","regress.mac",
"design.mac","tser.mac","arima.mac","mulvar.mac","math.mac",
"macanova.mac").  Each name in MACROFILES may also include a "path" with
directory or folder information.

You can easily add files to this list using pre-defined macro
addmacrofile() (see topic addmacrofile()) or replace it entirely by,
say, MACROFILES <- vector("mymacrofile1", "mymacrofile2").  If you often
use a particular macro file or files you might find it convenient to
have MACROFILES modified in your startup file.  See topic 'customize'.

@@@@automatic_search_for_macros#Automatic search for macros
Use of getmacros() is less necessary than it once was, since the default
behavior of MacAnova is now to search the files in MACROFILES for any
undefined macro you try to use.  For example, even if macro covar() has
not previously been read from file "MacAnova.mac", either by getmacros()
or macroread(),

  Cmd> cov <- covar(x)

will read covar() and then execute it.  However, is sometimes convenient
to use getmacros() to read in several macros at a time.  Moreover,
getmacros() echos the header lines on macros (unless you use quiet:T);
these often contain details about usage which you otherwise might miss.

@@@@example#Example
Example:  If MACROFILES has its default value
  Cmd> getmacros(covar, spectrum, "confound3")
retrieves macros covar() from file "macanova.mac", spectrum() from
"tser.mac" and confound3() from "design.mac".  The quotes around
confound3() are not needed but do no harm.
@@@@______

Note: Prior to 4/28/96, getmacros() searched only the file specified in
CHARACTER scalar MACROFILE.  For backward compatibility, if vector
MACROFILES does not exist, getmacros() uses MACROFILE.  It is an error
if neither MACROFILES or MACROFILE exist.

====getnotes()#general,variables
%%%%
getnotes(x [,silent:T]), x REAL, LOGICAL, CHARACTER or a structure,
  macro or GRAPH variable
%%%%
@@@@usage#Usage
getnotes(x) returns the "notes" attached to variable x, if any, as a
CHARACTER scalar or vector.  If x has no notes, the result is NULL and a
warning message is printed.

getnotes(x,silent:T) does the same, except when x does not have any
attached notes, the warning message is suppressed.

x can be any type of variable, including structure, macro and GRAPH.

@@@@see_also#Cross references
See also topics 'notes', attachnotes(), appendnotes(), and hasnotes().
@@@@______

====getoptions()#control
%%%%
getoptions(option1:T [,option2:T ... ] [,badoptok:T]), option1, option2,
  ...  option names.
getoptions() or getoptions(all:T) gets all option values as a structure
Type 'usage(options)' for a succinct list of all options and their
   permissible values.
%%%%
@@@@usage#Usage
getoptions(option1:T, option2:T, ...), where option1, option2, ... are
option names, returns the values of the specified options.  If more than
one option is specified, the result is a structure with appropriately
named components.  For example, getoptions(format:T) returns the default
format used in printing, getoptions(seeds:T) is equivalent to
getseeds(quiet:T), and getoptions(height:T,width:T) returns a structure
with components 'height' and 'width'.

getoptions() or getoptions(all:T) returns the values for all options.

getoptions(all:T, option1:F, option2:F,...) returns values for all
options except those specified.

@@@@legal_option_names#Legal option names
Legal option names are 'angles', 'batchecho', 'dumbplot', 'errors',
'findmacros', 'format', 'fstats', 'height', 'history', 'inline', 
'labelabove', 'labelstyle', 'keyboard', 'maxlinelen', 'maxwhile', 
'minpvalue', 'missing', 'nsig', 'pvals', 'prompt', 'restoredel', 
'savehistry', 'seeds', 'traceback' 'update', 'warnings', 'wformat', 
and 'width'.

See topic 'options' for details on these options.  Type 'usage(options)'
for a list of options with legal values and defaults.

Option name 'lines' is recognized as a synonym for 'height' for
compatibility with earlier versions.

On windowed versions, option 'scrollback' is also legal.

In the Mac OS 9 version, options 'font' and 'fontsize' are
also legal.

@@@@options_format_and_wformat#Options 'format' and 'wformat'
The value returned for 'format' or 'wformat' always has the type
specifier ('f' or 'g') at the end ("12.5g"), even if it was set with a
string starting with 'f' or 'g' ("g12.5").

@@@@badoptok_keyword#Keyword 'badoptok'
getoptions(option1:T[, option2:T, ...] ,badoptok:T) does the same,
except it is not an error if the options requested are legel.  If no
legal options are specified, getoptions() returns NULL.

This feature is intended to allow macros using new options to be written
in such a way that they are backward compatible with MacAnova versions
without the new options.

@@@@see_also#Cross references
See also restore(), save().
@@@@______

====getseeds()#random numbers
%%%%
getseeds([quiet:T])
%%%%
@@@@usage#Usage
getseeds() prints the current seeds and returns the current seeds in the
random number generator used by runi(), rnorm(), rbin() and rpoi() as an
"invisible" REAL vector of length 2.  See topic 'variables:"invisible"'.

getseeds(quiet:T) returns the seeds as a regular (not invisible) REAL
vector of length 2, but does not print them.

You can use getseeds() together with setseeds() to restart the random
number generators from the same point more than once.  If you retrieve
the seeds by 'seeds <- getseeds(quiet:T)', you can later reset the
random number generators to the same place by 'setseeds(seeds)'.

The seeds are saved by save() or asciisave() (unless you specify
'options:F') and are restored by restore().

@@@@see_also#Cross references
See also setseeds(), runi(), rnorm(), rbin(), rpoi().
@@@@______

====gettime()#general
%%%%
gettime(), gettime(quiet:T), or gettime(keep:T [,quiet:F])
gettime(interval:T), gettime(interval:T,quiet:T), or
   gettime(interval:T,keep:T [,quiet:F])
%%%%
@@@@usage#Usage
gettime() prints the time in seconds since the start of the run.

gettime(interval:T) prints the time in seconds since the last time
gettime() was used (since the start if this is the first usage).

gettime(quiet:T) and gettime(interval:T, quiet:T) do nothing but save
the current time for the next time gettime(interval:T) is used.

gettime(keep:T [, quiet:F]) returns the time since start as a REAL
scalar.  It prints nothing unless quiet:F is an argument.

gettime(interval:T, keep:T [, quiet:F]) returns the time since last use
as a REAL scalar.  It prints nothing unless quiet:F is an argument.

@@@@printing_elapsed_time_of_command#Printing elapsed time of command
You can create a macro that will print the elapsed time of an action by
  Cmd> timeit <- macro("gettime(quiet:T);{$0};gettime(interval:T)")
Then, for example,
  Cmd> timeit(x <- rnorm(1000);stuff <- describe(x))
will print time spent generating x and computing descriptive statistics.
See also topics macro(), 'macros'.

On most computers, gettime() returns the actual time elapsed as might be
measured with a stop watch.  On a few computers, the time is the amount
of central processor time used.  This will generally be less, often much
less than the actual elapsed time.

@@@@examples#Examples
Examples:
  Cmd> gettime()
  Time since start is 377.65 seconds.

  Cmd> gettime(quiet:T);mymacro(x,y);gettime(interval:T)
  Elapsed time is 3.6718 seconds

  Cmd> gettime(quiet:T);mymacro(x,y);gettime(interval:T,keep:T)
  (1)        3.699

  Cmd> gettime(quiet:T);mymacro(x,y);gettime(interval:T,keep:T,quiet:F)
  Elapsed time is 3.6523 seconds
  (1)       3.6523
@@@@______

====getusage()#general
%%%%
getusage([Topic1,Topic2,...] [,file:FileName or orig:T or \
  alt:T, silent:T])
getusage(Pattern) where Pattern has form "part*", "*part", or "*part*".
getusage(key:KeyNames), where KeyNames is a CHARACTER vector or "?"
%%%%
@@@@introduction#Introduction
getusage() is used by macro usage() to retrieve usage information from a
"help file", a text file in a special format.  It can be used directly,
but has the disadvantage that it searches only one file.

getusage() searches only the "current" help file.  This is initially
"macanova.hlp" but can be changed by keywords 'file', 'alt' and 'orig'.

@@@@usage#Usage
getusage() works identically to gethelp(), except it gives a only a
brief summary of the usage of commands, functions, and macros, instead
of full details.  On some general information topics such as 'options'
and 'graph_keys' it lists available items; on other general information
topics the usage is just a suggestion to read the full help.

getusage(...) is equivalent to gethelp(..., usage:T).

getusage(..., usage:F) is equivalent to gethelp(...).

getusage() returns an "invisible" LOGICAL scalar whose value is True
only when at least one topic requested was found.  The value may be
assigned or tested but will not be printed automatically.  See topic
'variables:"invisible"'.

getusage() scans only one help file.  See gethelp() for details.
Pre-defined macro usage(), used almost identically, scans all the files
named in CHARACTER vector HELPFILES.  See topic usage().

For many commands and macros, you can get more complete usage
information by help(topic, subtopic:"usage").

@@@@historical_notes#Historical notes
Prior to Version 4.12, getusage() was named usage().  usage() is now a
macro that uses getusage() to search several help files.  If you want
usage() to work identically to getusage(), you can define a simplified
version by:
  Cmd> usage <- macro("getusage($0)")

Prior to Version 4.11, topics longer than 12 characters
('transformations', for example) or that were control words ('if',
'while', 'for', 'else', 'elseif', 'break', 'breakall') had to be quoted.
This is no longer the case.

@@@@see_also#Cross references
See gethelp() for full details.
@@@@______

====glm%#glm,anova,categorical data,multivariate analysis,regression
%%%%
Type usage(command), where command is anova, fastanova, glmfit, ipf,
  logistic, manova, poisson, probit, regress, screen, robust
%%%%
@@@@introduction#Introduction
The commands for analyzing linear and generalized linear models are as
follows:
   anova(), fastanova()              Analysis of Variance
   glmfit()                          Generalized linear model analysis
   ipf(), logistic()                 Logistic Regression
   manova(),                         Multivariate Analysis of Variance
   poisson()                         Log linear models
   probit()                          Probit analysis
   regress()                         Linear Regression
   robust()                          Robust Regression
   screen()                          Best subset linear regression

These are generally referred to as GLM commands in help topics.  See
their individual help entries for details.  Type help(key:"glm") for a
list of help entries related to analyzing linear and generalized linear
models.

In addition, wtanova(), wtmanova() and wtregress() do weighted ANOVA,
MANOVA and regression.  Since the same computations are done when
weights are specified using keyword 'weights' or 'wts' (see below),
these are not further mentioned here.

glmfit() is a general function that can, with appropriate keyword
arguments, be used instead of anova(), logistic(), poisson(), and
probit().  In the future, additional options will allow analyses not
possible at present.

All GLM commands have certain elements in common.

@@@@model
Model
  The first argument of a GLM command specifies a model as a quoted
  string or CHARACTER variable.  Examples are regress("y=x1+x2+x3") and
  anova("x=a + a.b").  If the model is absent (for example, anova() or
  logistic(,n)) the most recent GLM model is assumed or the model in
  CHARACTER variable STRMODEL is used.  Type help(models) for
  information on how to specify a model.

@@@@missing_values
Treatment of MISSING values
  When there are MISSING values in any of the variables in a GLM model,
  any case with any MISSING values is omitted entirely.  The maximum
  level of any factor is taken to be the maximum level on any of the
  complete data cases.

@@@@side_effect_variables_created
Side effect variables
  All GLM commands but screen() create certain side-effect variables.
  The most important are the following (not all may be produced by every
  command).

   STRMODEL, a CHARACTER scalar containing the model used.

   TERMNAMES, a CHARACTER vector containing the names of the terms in
   the model including the error terms.  When the GLM command does an
   iterative fit without keyword phrase 'inc:T' (see topic 'glm_keys'),
   the value of TERMNAMES still has the same number of elements but has
   the form vector("","",...,"Overall model","ERROR1"), reflecting the
   fact that only model and error deviances are computed.

   DEPVNAME, a CHARACTER scalar containing the name of the response
   variable in the model.

   SS, a REAL vector of sums of squares or deviances, one for each term
   in the model.  For manova() this is an array of SSCP matrices, with
   the first subscript indexing the term.  Except when 'marginal:T' is
   an argument to anova(), manova() or robust(), these are computed
   sequentially and measure the importance of a term after fitting
   previous terms, and ignoring later terms.  The first dimension of SS
   has labels identical to TERMNAMES.  After manova(), dimensions 2 and
   3 are labeled with the column labels of the response variable if it
   has labels or by vector("(1)","(2)", ...) otherwise.  After a GLM
   command that does an iterative fit without keyword phrase 'inc:T',
   the value of SS is vector(0,0,...,ModelDeviance,ErrorDeviance).

   DF, a REAL vector containing the degrees of freedom associated with
   each term in the model.  After a GLM command that does an iterative
   fit without keyword phrase 'inc:T', the value of DF is
   vector(0,0,...,ModelDF,ErrorDF).

   RESIDUALS, a REAL vector or matrix of residuals from the fitted
   model.  For any case with MISSING values in the data, RESIDUALS is
   MISSING.

   WTDRESIDUALS, a REAL vector or matrix of weighted residuals from the
   fitted model.  For analyses using iteratively re-weighted least
   squares sucu as logistic(), probit(), or poisson(), the weights are
   those used on the last iteration.  For any case with MISSING values
   in the data, WTDRESIDUALS is MISSING.  WTDRESIDUALS is not created by
   anova(), regress() or manova() unless weights are provided.

   XTXINV (regress()), the inverse or generalized inverse of X'X or
   X'WX, where X is the n by k matrix of predictors, including the
   constant vector if it is in the model, and W is the diagonal matrix
   of weights, if any.

   HII, the REAL vector of leverages, the diagonal elements of
   X(XTXINV)X' or W X(XTXINV)X', where W is the diagonal matrix of
   weights, if any.

   COEF (regress() only), the model coefficients.

It is an error if any GLM command finds that any side effect variable is
locked (see lockvars(), unlockvars(), 'variables:"locked_variables"').

@@@@private_information#Private information
Besides creating side effect variables, most GLM commands save "private"
information about the analysis.  This is used by commands such as
regpred(), contrast(), coefs() and secoefs().  It can be retrieved by
command modelinfo().  This information is not preserved by save() and
asciisave() unless keyword phrase 'all:T' is used.  It is discarded when
you assign a value to STRMODEL or delete STRMODEL.

@@@@see_also#Cross references
See topic 'glm_keys' for a list of keyword phrases recognized by more
than one GLM command.
@@@@______

====glm_keys%#glm,anova,regression,multivariate analysis,categorical data
%%%%
Type help(glm_keys) for a list of keyword phrases recognized by more
than one GLM command.
%%%%
Here is a list of keyword phrases recognized by more than one GLM
command:

   Keyword phrases  Commands recognizing
   ---------------  -------------------------------------------
@@@@print
   print:F          All GLM commands
    Directs that most of the output to the screen is suppressed,
    although side effect variables are created.

@@@@silent
   silent:T         All GLM commands but screen()
    Directs that all output except error messages is suppressed; side
    effect variables are computed when there are no errors,

@@@@coefs
   coefs:F          All GLM commands but screen(), regress(),
                    fastanova(), ipf(), robust();
    Suppresses the computation of coefficients or a generalized inverse
    to X'X (X'WX when there are weights).  Except in the case of
    balanced ANOVA, coefs() and secoefs() cannot be used to retrieve
    coefficients later.  In addition, some of modelinfo() options are
    effectively disabled after using 'coefs:F' on a GLM command.
    'coefs:F' is not legal with 'marginal:T'.

@@@@fstats
   fstats:T         regress(), anova(), manova(), robust()
    Directs that F-statistics and P values are computed and printed.
    The denominator is the mean square for the next following term whose
    name is of the form "ERROR1", "ERROR2", ... .  For manova(),
    statistics are given separately for each variable and printing of
    the SS/SP matrices is suppressed, although they are created as side
    effect variables.

@@@@pvals
   pvals:T          All GLM commands except screen()
    Directs that F or Chi-Squared P values are computed and printed for
    F-statistics, t-statistics, and deviances.  pvals:F suppresses
    P values when they might otherwise be printed.

@@@@inc
   inc:T         poisson(), ipf(), logistic(), glmfit()
    Specifies that an incremental analysis of deviance table is to be
    computed and printed.  No longer legal on robust().

@@@@marginal
   marginal:T    anova(), manova(), robust()
    Specifies that SS (SS/SP matrices for manova()) are computed
    marginally.  When there are no empty cells, and sometimes when there
    are, the computed SS or SS/SP are equivalent to SAS Type III
    quantities.  'marginal:T' is not legal with 'coefs:F'.

@@@@maxiter
   maxiter:n     fastanova(), poisson(), ipf(), logistic(), robust(),
                 glmfit()
    Specifies the maximum number of iterations allowed in fitting

@@@@eps
   eps:smallVal  fastanova(), poisson(), ipf(), logistic(), robust(),
                 glmfit()
    Specifies the a threshhold in relative change of objective function
    for determining when convergence has been reached

@@@@problimit
   problimit:smallVal glmfit() with 'dist:"binomial"', logistic(),
                 probit()
    Restricts iteration so that fitted probabilities are between
    smallVal and 1 - smallVal, where 1e-15 <= smallVal < .0001.

@@@@weights
   wts:vec       anova(), manova(), regress()
   weights:vec
    Specifies a REAL vector to be used as weights.  'wts' and 'weights'
    are equivalent.

@@@@offsets
   offsets:vec   poisson(), logistic(), probit(), glmfit()
    Causes the model to be fit to link to be 1*vec + Model, where vec is
    a REAL vector the same length as response y.  vec must be in the
    same units as the link function.  Thus for poisson() and ipf(), vec
    should be units of log(E[response]); for logistic(), vec should be
    in units of log(p/(1-p)) and for probit() vec should be in units of
    invnor(p).

    When vec is a linear combination of X-variables in the model, say
    b01*x1 + b02*x2 + b03*x3, the coefficients computed for x1, x3 and
    x5 will b1-b01, b2-b02 and b3-b03, where b1, b2 and b3 are the
    values that would be computed when offsets:vec is not an argument.
    The residual deviance is not affected.  If inc:T is an argument, the
    deviance associated with x1, x2, and x3 reflects the departure of b1
    from b01, b2 from b02, and b3 from b3.  This makes it possible to
    test a hypothesis that one or several coefficients to have specified
    values.  See logistic(), poisson() and probit() for examples.

@@@@printing_F_and_P_value#Printing F and P value
If neither fstats:T nor fstats:F is an argument, for anova() and
fastanova() (but not manova()), the printing of F-statistics is
controlled by option 'fstats'.  See topic 'options'.

If neither pvals:T nor pvals:F is an argument, for all GLM commands
except manova(), robust() and screen(), the printing of P values is
controlled by option 'pvals', except that if options 'pvals' has value
False, P values will be printed if F-statistics are.

Sums of squares or deviances are normally computed sequentially.  For
anova(), manova(), and robust() these are SAS Type I quantities.  Thus
in the unbalanced case, several analyses may be necessary to compute all
the sums of squares or deviances needed.

@@@@marginal2#Effect of 'marginal:T'
Keyword phrase, 'marginal:T', when it can be used, causes SS or SS/SP to
be computed differently.  When there are no empty cells in the design
and no aliased variates, and sometimes when there are, the SS or SS/SP
computed are SAS Type III quantities.  In every case, they are numerator
SS or SS/SP for a test that all the coeffients of non-aliased
X-variables in a term are 0, where aliasing is determined by the
original order of the sequential fit.  If there is aliasing, the
quantities computed may depend on the order in which the terms are fit.
@@@@______

====glmfit()#glm,anova,regression,categorical data
%%%%
glmfit([Model] [,dist:distName,link:linkName, n:denom, incr:T,\
  print:F or silent:T, maxiter:m, epsilon:eps, coefs:F, offsets:OffVec,\
  scale:sigma]), distName and linkName CHARACTER scalars, denom > 0
  REAL scalar or vector, integer m > 0, REAL eps > 0, REAL vector OffVec
%%%%
@@@@usage#Usage
glmfit(Model,dist:DistName ,link:LinkName,...) does a generalized linear
model analysis with assumed response distribution DistName and link
function LinkName, somewhat in the manner of program GLIM.  The response
variable y must be a vector (isvector(y) is True).

See topic 'models' for information on and examples of quoted string or
CHARACTER scalar Model.

Current legal values for DistName are "binomial", "poisson", and
"normal" (or "gaussian").  If DistName is "binomial" or "poisson", you
must have y[i] >= 0.

Current legal values for LinkName are "logit", "probit", "log", and
"identity".

If dist:DistName is omitted, the default DistName is "normal".

If link:LinkName is omitted the default LinkName depends on DistName --
"logit" for "binomial", "log" for "poisson", and "identity" for
"normal".

Because of these defaults, glmfit(Model), with no distribution or link
specified, is equivalent to anova(Model, unbalanced:T).

@@@@binomial_distribution#Binomial response variable
If DistName is "binomial" you must specify the number of trials using
keyword 'n' as for logistic() or probit().  The value Denom for 'n' must
either be a REAL scalar >= max(y) or a REAL vector of the same length as
y with Denom[i] >= y[i].

@@@@algorithm_and_output#Algorithm and output
Except when DistName is "normal" and LinkName is "identity", an
iterative algorithm is used to model link(E[y]) or link(E[y/Denom]) as a
linear function of X-variables associated with the right hand side of
Model.  Normally a two line Analysis of Deviance table is printed.  Line
1 is the difference 2*L(1) - 2*L(0), where L(0) is the log likelihood
for a model with all coefficients 0 and L(1) is the maximized log
likelihood for the model fit.  Line 2 is 2*L(2) - 2*L(1) where L(2) is
the maximized log likelihood under a model fitting one parameter for
every y[i].  Under certain conditions, the latter can be used to test
the goodness of fit of the model using a chi-squared test.  When
DistName is "normal" and LinkName is "identity", an Analysis of Variance
table is printed including all terms.

@@@@side_effect_variables_created#Side effect variables created
glmfit() sets the side effect variables RESIDUALS, WTDRESIDUALS, SS, DF,
HII, DEPVNAME, TERMNAMES, and STRMODEL.  See topic 'glm'.  With DistName
is "normal" and LinkName is "identity", SS contains the ANOVA sums of
squares; otherwise SS contains deviances.  After an iterative fit
without keyword phrase 'inc:T' (see below), TERMNAMES has value
vector("","", ...,"Overall model","ERROR1"), DF has value vector(0,0,
...,ModelDF,ErrorDF) and SS has value vector(0,0,...,ModelDeviance,
ErrorDeviance).

@@@@inc_keyword#Keyword 'inc'
glmfit(Model,dist:DistName,link:LinkName,inc:T,...) computes the full
fitted model and all partial models -- only a constant term, the
constant and the first term, and so on.  It prints an Analysis of
Deviance table, with one line for each term, representing a difference
2*L(i) - 2*L(i-1) where L(i) is the maximumized log likely for a model
including terms 1 through i, plus the deviance of the complete model
labeled as "ERROR1".  Each line except the last can be used in a
chi-squared test to test the significance of the term on the assumption
that the true model includes no later terms.  The value of 'inc' is
ignored when DistName is "normal" and LinkName is "identity".

@@@@relationship_to_other_functions#Relationship to other functions
The use of glmfit() provides an alternative method to specify a logistic
or probit analysis of binomial responses, or a log linear analysis of
Poisson responses.

  Function                DistName      LinkName
  logistic()             "binomial"    "logit"
  probit()               "binomial"    "probit"
  poisson()              "poisson"     "log"
  anova()                "normal"      "identity"

In the future additional distributions such as "gamma" will be
implemented, as well as additional links such as "sqrt", "recip", or
"power".  If you specify an unimplemented combination of LinkName and
DistName, an informative error message is printed.

@@@@problimit_error_message#Problimit error message
When fitting a model with a binomial dependent variable, a warning
message similar to the following
   WARNING: problimit = 1e-08 was hit by glmfit() at least once
usually indicates either the presence of an extreme outlier or a best
fitting model in which many of the probabilities are almost exactly 0 or
1.  The latter case may not represent any problem, since the fitted
probabilities at these points will be 1e-8 or 1 - e-8.  You can try
reducing the threshold using keyword 'problimit' (see below), but you
will probably just get the message again.

                     Other Keyword Phrases
Keyword phrase  Default  Meaning
@@@@maxiter_keyword#Keyword 'maxiter'
  maxiter:m       50     Positive integer m is the maximum number of
                         iterations that will be allowed in fitting

@@@@epsilon_keyword#Keyword 'epsilon'
  epsilon:eps    1e-6    Small positive REAL specifying relative error
                         in objective function (2*log likelihood)
                         required to end iteration

@@@@problimit_keyword#Keyword 'problimit'
  problimit:small 1e-8   With dist:"binomial", iteration is restricted
                         so that no fitted probabilities are < small
                         or > 1 - small.  Value of small must be between
                         1e-15 and 0.0001.

@@@@offsets_keyword#Keyword 'offsets'
  offsets:OffVec  none   Causes model to be fit to link to be 1*Offvec +
                         Model, where OffVec is a REAL vector the same
                         length as response y.  OffVec must be in the
                         same units as the link function, say, logits,
                         logs, or probits.  See topic 'glm_keys' for
                         more information and poisson(), logistic() and
                         probit() for examples.

@@@@scale_keyword#Keyword 'scale'
  scale:sigma      1     sigma must be a positive REAL scalar or ?
                         (MISSING).  Its value will replace a default
                         multiplier used by secoefs() and contrast() to
                         compute standard errors.  If the value is
                         MISSING, sigma will be computed as sqrt(SS[m]/
                         DF[m]), where m = length(SS).  The default is 1
                         unless dist is "normal" when it is sqrt(SS[m]/
                         DF[m]).  In secoefs(), scale multiplies the
                         square roots of the diagonal values of the
                         inverse of X'WX, where X is the matrix of
                         X-variables, and W is a diagonal matrix of
                         weights computed using the converged fit.

@@@@see_also#Cross references
See topic 'glm_keys' for details on keyword phrases print:F, silent:T,
coefs:F.

See also topics logistic(), poisson(), probit(), 'glm'.
@@@@______

====glmpred()#glm,regression,anova,categorical data
%%%%
glmpred(variates,factors [, estimate:F, seest:F, sepred:T, n:N,
  silent:T]), variates and factors REAL vectors or matrices or NULL, N a
  positive scalar or REAL vector with positive elements.
%%%%
@@@@usage#Usage
glmpred(Variates, Factors) computes estimates of the expected value of
the response variable y for specified values of any variates and levels
of any factors in the latest GLM model.  It returns a structure with
REAL components (vectors, except after manova()) "estimate" and "SEest".

If there are no variates in the model, Variates should be NULL (see
topic 'NULL').  Otherwise, Variates should be REAL.  If there are Nvar
variates in the model, Variates should either be a vector of length Nvar
containing values for each of the variates, or a matrix with Nvar
columns, with each row containing values for each variate.

If there are no factors in the model, Factors should be omitted or
explicitly NULL.  Otherwise, Factors should be REAL.  If there are Nfac
variates in the model, Factors should either be a vector of length Nfac
containing levels for each of the factors, or a matrix with Nfac
columns, with each row containing levels for each factor.

If either Variates or Factors contains data for only one case, it is
used for all cases.  Otherwise, you must have nrows(Variates) =
nrows(Factors).

Caution: After anova(), manova() and regress(), standard errors are
computed using the final error mean square in the model.  This may not
be appropriate with mixed models, including split plot designs.

@@@@silent_keyword#Keyword 'silent'
glmpred(Variates, Factors, silent:T) does the same except that certain
advisory messages are suppressed.  'silent:T' can be used with any other
keywords.  The default value of 'silent' is False unless the value of
option' 'warnings' is False.

@@@@sepred_seest_and_estimate_keywords#Keywords 'sepred', 'seest' and 'estimate'
glmpred(Variates, Factors, sepred:T) adds component SEpred to the output
structure containing a vector or matrix of prediction standard errors.
This is only permissible after regress(), anova() or manova() and their
weighted alternatives.

glmpred(Variates, Factors, seest:F) suppresses the computation of
standard errors.

glmpred(Variates, Factors, estimate:F) suppresses the computation of
expected values.  This option is legal only after anova(), manova(),
regress() and their weighted alternatives.

You cannot use glmpred() after fastanova() or ipf() or when coefs:F was
used on the preceding GLM command.

@@@@after_binomial_response_GLM#After binomial response GLM
After GLM functions involving a Binomial response variable (logistic(),
probit(), glmfit(...,dist:"binomial")), the values computed are the
estimated probabilities p of "success" associated with each case (set of
values).  In this case, you can also use keyword phrase n:N, where N is
a REAL variable, to specify the number of trials for each case.  N can
be a scalar or a vector whose length matches the number of cases.  The
resulting estimated values are N*phat, where phat are the estimated
probabilities.

@@@@after_other_nonlinear_GLMs#After other nonlinear GLMs
After GLM functions such as poisson(), logistic(), or probit(), where
the expectation of the response is a non-linear function of a linear
combination of the predictors, the standard error is computed from the
expectation and standard error in the linear scale using the
delta-method.  When the response is binomial and you also use n:N, the
standard errors are those of N*p.

@@@@assumption#Assumption
Comment: Standard errors are computed on the assumption that all effects
are fixed and not random.  When this is not appropriate, the standard
errors will usually indicate more precision than is warrented.

@@@@example#Example
Examples:
  After regress(), glmpred(x,sepred:T) is equivalent to regpred().
  After anova("y=x+a+b"), x a variate, a and b factors,
     glmpred(x, hconcat(a,b)) computes fitted values and their standard
     errors for each case.
  glmpred(modelvars(variates:T), modelvars(factors:T)) computes fitted
  values and their standard errors for each case, regardless of the
     model.

@@@@see_also#Cross references
See also glmtable(), glmpred(), regpred(), modelinfo(), popmodel(),
pushmodel().
@@@@______

====glmtable()#glm,anova
%%%%
glmtable([wtdmeans:T or x:vals, estimate:F, seest:F, sepred:T, n:N]\
  [,silent:T]) or
glmtable(Term,[wtdmeans:T or x:vals, estimate:F, seest:F, sepred:T,\
  n:N] [,silent:T]) where vals is REAL vector and TERM is CHARACTER
  scalar of form "A.B. ...", where A, B are factors in current GLM
  model, N is a positive REAL scalar or vector or array of positive
  numbers.
%%%%
@@@@usage#Usage
glmtable() computes tables of fitted values (estimated cell expected
values) and their standard errors based on the computations of the most
recent GLM (generalized linear or linear model) command such as anova()
or poisson().  It returns a structure with components "estimate" and
"SEest" containing the tables, each of which has a dimension for each
factor in the model, in the order the variables appear in the model.  If
there are variates in the model, the fitted values are computed with
each variate set to its unweighted mean value and thus are what are
sometimes called the covariate adjusted cell means.

If only one array of values is computed, glmtable() returns that array,
not a structure.

@@@@silent_keyword#Keyword 'silent'
glmtable(silent:T) does the same except that certain advisory messages
are suppressed.  'silent:T' can be used with any other keywords.  The
default value of 'silent' is False unless the value of option'
'warnings' is False.

@@@@sepred_seest_and_estimate_keywords#Sepred seest and estimate keywords
glmtable(sepred:T) adds component SEpred to the output structure
containing a table of prediction standard errors.  This is only
permissible after regress(), anova() or manova() and their weighted
alternatives.

glmtable(seest:F) suppresses the computation of standard errors.

glmtable(estimate:F) suppresses the computation of expected values.
This option is legal only after anova(), manova(), regress() and their
weighted alternatives.

Caution: After anova(), manova() and regress(), standard errors are
computed using the final error mean square in the model.  This may not
be appropriate with mixed models, including split plot designs.

@@@@wtdmeans_keyword#Keyword 'wtdmeans'
glmtable(wtdmeans:T [,...]) does the same except it adjusts cell fitted
values to the weighted means of the variates.  You can use wtdmeans:T
only when there are variates and when the previous GLM command used
unweighted OLS (anova() or manova() with no weights supplied).  This
option would be probably appropriate when the weights were proportional
to sample sizes.

@@@@x_keyword#Keyword 'x'
glmtable(x:Vals [,...]), where Vals is a REAL vector with length = the
number of variates (non-factors) in the model, does the same
computation, except it uses the elements of Vals instead of unweighted
or weighted variate means.  This option allows you to estimate cell
means that are adjusted to any level of the covariates.  Use of x:Vals
is an error if there are no variates in the current GLM model.

@@@@marginal_table#Marginal table
glmtable(Term [,...]) returns an estimated marginal table for the
factors specified by Term.  Term is a quoted string or CHARACTER scalar
of the form "Name1.Name2.Name3....", where Name1, Name2, ... are names
of factors in the current GLM model.  If there are k factor names in
Term, the value will be an array with k dimensions (vector if k = 1,
matrix if k = 2), with the dimensions ordered in the same order as in
the model, not the order in Term if that is different.  You cannot
use glmtable(term [,...]) after anova() with a balanced design unless
Term includes all the factors in the model.
  Example:
  Cmd> glmtable("a.b", x:17) # same as glmtable("b.a",x:17)

glmtable(term:k [,...]) is equivalent to glmtable(TERMNAMES[k] [,...]),
computing the marginal table matching term k in the model.
Example:
  Cmd> glmtable(term:3, x:17).

You can use sepred:T when estimating a marginal table.

Comment: When the marginal table for any term in the model contains
empty cells, especially when a factor is nested in another with
different numbers of levels, the estimated means may not be what you
want.

@@@@after_binomial_GLM#After binomial GLM
For GLM functions involving a binomial response variable (logistic(),
probit(), glmfit() with dist:"binomial"), the values computed are the
estimated probabilities p of "success" associated with each cell.  In
this case, you can also use keyword phrase n:N, where N is a REAL
variable, to specify the number of trials for each cell.  N can be a
scalar, a vector whose length matches the size of the table, or a matrix
or array whose dimensions match those of the table.  The resulting table
is a table of N*p.

@@@@after_other_nonlinear_GLMs#After other nonlinear GLMs
After GLM functions such as poisson(), logistic(), or probit(), where
the expectation of the response is a non-linear function of a linear
combination of the predictors, the standard error is computed from the
expectation and standard error in the linear scale using the
delta-method.  When the response is binomial and you also use n:N, the
standard errors are those of N*p.  You cannot use seest:T or sepred:T
after fastanova() or ipf().

@@@@assumption#Assumption
Comment: Standard errors are computed on the assumption that all effects
are fixed and not random.  When this is not appropriate, the standard
errors will usually indicate more precision than is warrented.  In
particular, this is would be the case when one factor indexes replicates
in a randomized block design and you use glmtable(Term,seest:T) to
estimate treatment means, where Term contains all the factors except
blocks.

@@@@after_nonlinear_GLMs#After nonlinear GLMs
After fitting a non-linear model by logistic(), probit(), poisson(), or
glmfit(), when Term doesn't contain all the factors in the model,
glmtable(Term) first computes the estimated marginal table in the linear
scale (logit, probit, or log) and then transforms it back into the scale
of the response.  This means that the computed marginal table is not the
marginal means of the fitted table.  For example, if b is a factor with
3 levels, after logistic("y=a*b", n:40), sum(glmtable("a.b"))/3 is not
the same as glmtable("b").

@@@@limitation#Limitation
When keyword phrase coefs:F was an argument on the most recent GLM
command, glmtable() is not available.

@@@@see_also#Cross references
See also topics anova(), anovapred(), glmpred(), regpred(), modelinfo(),
popmodel(), pushmodel(), 'glm'.
@@@@______

====goodfactors()#general
%%%%
goodfactors(n), n an integer scalar or vector
%%%%
@@@@usage#Usage
goodfactors(n), where n is a vector of positive integers < 2^52 =
4503599627370496, returns an integer vector the same length as n whose
i-th element is the smallest integer >= n[i] having no prime factors
larger than 29.  It is designed to be used to choose legal lengths of
vectors to be Fourier transformed using rft(), hft() or cft().

goodfactors(n,m), where n is the same and m is a positive integer
scalar, does the same, except the i-th element of the result is the
smallest integer >= n[i] having no prime factors larger than m.

NOTE: Because the product of "unpaired" prime factors can't be too
large, it is not guaranteed that a value returned by goodfactors() is
actually a legal length for the Fourier transform functions.  For
example, goodfactors(255255) = 255255, but 255255 = 3*5*7*11*13*17 is
not a legal length.

Example:
  Cmd> goodfactors(vector(217,1409))
  (1)          220         1421

@@@@see_also#Cross references
See also primefactors(), cft(), hft(), rft().
@@@@______

====grade()#ordering
%%%%
grade(x [ ,down:T]), x REAL or CHARACTER or a structure with all REAL
  or all CHARACTER components.
%%%%
@@@@usage#Usage
grade(a) is similar to rank(a), producing a vector, matrix, or array of
the same shape as a, but with the indices of the minimum, second
smallest, ..., maximum values in each column in place of the ranks.
For example, if x is vector(3.2,1.4,5.6,2.1), grade(x) computes the
vector(2,4,1,3) since x[2], x[4], x[1], x[3] are the values of x in
increasing order.  The basic property is that, if x is a vector,
x[grade(x)] is the same as sort(x).

Argument a can be either REAL or CHARACTER.  When a is CHARACTER,
ordering is based on the ASCII collating sequence.  See sort() for the
complete ordering of characters.

grade(a,down:T) or simply grade(a,T) does the same except the underlying
sort is in decreasing order so that grade(a,down:T)[1,] computes the
case (row) numbers of the maximum of each column.

Two uses for grade() are x[grade(x[,i]),] which reorders the rows of x
so that column i is ordered, and grade(x)[1,] or grade(x,T)[1,] which
compute the indices of the minimum and maximum of each column of x.

@@@@structure_argument#Structure argument
It is also acceptable for x to be a structure, whose non-structure
components are all REAL or all CHARACTER.  In that case, grade() returns
a structure of the same form, each of whose non-structure components is
the result of applying grade() to the corresponding component of x.

@@@@treatment_of_missing_values#Treatment of MISSING values
If there are k MISSING values of a column, the last k elements of the
result are the indices of the MISSING values.  For example,
grade(vector(3,1,?,0,?)) computes vector(4,2,1,3,5).  Consequently, if x
is a vector, x[grade(x)] and x[grade(x,down:T)] compute the same vector
as sort(x) and sort(x,down:T), even when there are MISSING values.

@@@@treatment_of_ties#Treatment of ties
When there are ties, the values computed for the tied elements are
unpredictable but still satisfy that x[grade(x),] is the same as
sort(x).

@@@@examples#Examples
Examples:
  Cmd> grade(vector(27,22,25,26,22,21,?,24))
yields vector(6,2,5,8,3, 4,1,7), since the minimum (21) is in position
6, the 2nd and 3rd smallest (22) are in positions 2 and 5, . . ., the
largest (27) is in position 1, and the only MISSING value is in position
7.

  Cmd> grade(vector(27,22,25,26,22,21,?,24),down:T)
yields vector(1,4,3,8,2,5,6,7).

@@@@see_also#Cross references
See also sort(), rank().
@@@@______

====graphicshelp()#general,plotting
%%%%
graphicshelp(topic1 [, topic2 ...] [,usage:T] [,scrollback:T])
graphicshelp(topic, subtopic:Subtopics), CHARACTER scalar or vector
  Subtopics
graphicshelp(topic1:Subtopics1 [,topic2:Subtopics2 ...])
graphicshelp(key:Key), CHARACTER scalar Key
graphicshelp(index:T [,scrollback:T])
%%%%
@@@@usage#Usage
graphicshelp(Topic1 [, Topic2, ...]) prints help on topics Topic1,
Topic2, ... related to macros in file graphics.mac.  The help is taken
from file graphics.mac.

graphicshelp(Topic1 [, Topic2, ...] , usage:T) prints usage information
related to these macros.

graphicshelp(index:T) or simply graphicshelp() prints an index of the
topics available using graphicshelp().  Alternatively,
help(index:"graphics") does the same thing.

graphicshelp(Topic, subtopic:Subtopic), where Subtopic is a CHARACTER
scalar or vector, prints subtopics of topic Topic.  With subtopic:"?", a
list of subtopics is printed.

graphicshelp(Topic1:Subtopics1 [,Topic2:Subtopics2], ...), where
Suptopics1 and Subtopics2 are CHARACTER scalars or vectors, prints the
specified subtopics.  You can't use any other keywords with this usage.

In all the first 4 of these usages, you can also include help() keyword
phrase 'scrollback:T' as an argument to graphicshelp().  In windowed
versions, this directs the output/command window will be automatically
scrolled back to the start of the help output.

@@@@key_keyword#Keyword 'key'
graphicshelp(key:key) where key is a quoted string or CHARACTER scalar
lists all topics cross referenced under Key.  graphicshelp(key:"?")
prints a list of available cross reference keys for topics in the file.
@@@@______

graphicshelp() is implemented as a predefined macro.

@@@@see_also#Cross references
See help() for information on direct use of help() to retrieve
information from graphics.mac.
@@@@______

====graphs%#plotting
%%%%
Type usage(cmd) or help(cmd) where cmd is plot, chplot, lineplot,
  stringplot, boxplot, addpoints, addlines, addchars, addstrings or
  showplot
Type help(graph_keys) for information on graphic keywords 'x', 'y',
  'symbols', 'strings', 'title', 'xlab', 'ylab', 'xmin', 'xmax', 'ymin',
  'ymax', 'logx', 'logy', 'xaxis', 'yaxis', 'borders', 'add', 'keep',
  'show', 'dumb', 'height', 'width', 'file', 'new', 'landscape', 'ps',
  'epsf', 'window', 'pause', 'lines', 'linetype', 'thickness', 'ticks',
  'xticks', 'yticks', 'xticklen', 'yticklen', 'xticklabs', 'yticklabs',
  'screendump' and 'keys'
Type help(graph_files) for information on how to save a plot in a file
  using keywords 'file', 'new, 'ps', 'screendump', and 'epsf'.
Type help(graph_border) for information on controlling which borders
  will be drawn using keyword 'borders'
Type help(graph_ticks) for information on modifying default tick mark
  placement and labeling using keywords 'ticks', 'xticks', 'yticks',
  'xticklen' 'yticklen', 'xticklabs' and 'yticklabs'.
Type help(GRAPHWINDOWS) for information on special variable GRAPHWINDOWS
Type help(graph_assign) for information on making plots by assigning to
  GRAPHWINDOWS
%%%%
@@@@basic_plotting_commands#Basic plotting commands
The basic plotting commands are as follows:
  plot(x,y)                   Plot of columns of y against x
  lineplot(x,y)               Connected line plot of columns of y
                              against x
  chplot(x,y,symbols:ch)      Plot of columns of y against x using
                              symbols specified by ch
  stringplot(x,y,strings:s)   Draw labeling information in s at
                              positions defined by x and y
  boxplot(x1,x2,...,xk)       Box plots of vectors x1, ..., xk
  boxplot(structure(x1,...xk))
  addpoints(x,y)              Add data to an existing graph
  addlines(x,y)               Add line connected data to an existing
                              graph
  addchars(x,y,symbols:ch)    Add data to an existing graph using
                              symbols specified by ch
  addstrings(x,y,strings:s)   Add labeling information in s at coord-
                              inates in x and y in an existing graph
  showplot()                  Redisplay previously displayed graph

@@@@arguments_of_basic_plotting_commands#Arguments of basic plotting commands
Arguments x and y can be replaced by a structure with at least two
components which are interpreted as x and y.  Any additional components
are ignored.  For example, plot(x,y) and plot(structure(x,y,z)) are
equivalent.

It is not an error when x or y is NULL; a warning message is printed and
no plotting occurs.

Except for stringplot() and addstrings(), any points or lines outside
the border of the plot are omitted.  The exception for stringplot() and
addstrings() allows you to place custom labels outside the frame of the
graph.

@@@@assignment_to_GRAPHWINDOWS#Assignment to GRAPHWINDOWS
You can also draw a graph by a command like
  Cmd> GRAPHWINDOWS[1] <- structure(x:height,y:weight [,...])
where any additional arguments are graphics keyword phrases.  See topics
'graph_assign' and 'GRAPHWINDOWS' for details.

@@@@keyword_use#Keyword use
See topic 'graph_keys' for information on optional graphics keyword
phrases.  You can use some of these to specify axis labels and a title
or plotting limits.  Examples are xmin:0, xmax:10,ymin:-1, ymax:1,
xlab:"X axis label", ylab:"Y axis label", and title:"Title above graph".
You can use others to specify whether the graph is to be displayed,
written to a file, or be saved in the form of a GRAPH variable.  Using
keyword 'keys', you can specify such keyword information as components
of a structure.

@@@@other_references#Other references
See topic 'graph_files' for information on how to save a plot in a file
using keywords 'file', 'new, 'ps', 'screendump', and 'epsf'.

See topic 'graph_ticks' for information on using keywords 'ticks',
'xticks', 'yticks', 'xticklen', 'yticklen', 'xticklabs' and 'yticklabs'
to modify default tick mark placement and labeling.

See topic 'graph_border' for information on using keyword 'borders' to
control which borders will be drawn

@@@@use_of_mouse#Use of mouse
In windowed versions you can use the mouse in a graphics window to
specify the positions of points, lines or rectangles to be drawn into
the graph.  You can do the same, with some restrictions, in the
Unix/Linux version using Tektronix emulation with an emulator that
implements graphical input mode.  See Mouse().

@@@@logarithmic_scaling
                      Logarithmic scaling of axes
Keyword phrases 'logx:T' and/or 'logy:T' specify that logarithmic
scaling is to be used for the corresponding axis.  When plotted, the
values are transformed to logarithms, but tick marks are still in the
original units.  For example, plot(x,y,logy:T) creates a semi-log plot,
with a linear x-axis and a logarithmic y-axis and plot(x,y,logx:T,
logy:T) creates a log-log plot.

With logx:T, any data points with x <= 0 are treated as if they had
MISSING values as are data points with y <= 0 when you use logy:T.  A
warning message is given.

@@@@low_resolution_plots
                     Low resolution ("dumb") plots
By default, all plotting commands produce high resolution graphs.
Keyword phrase 'dumb:T' on any plotting command directs that the graph
should be "dumb", that is a low resolution plot using characters that
can be printed on any printer.  If you prefer to have dumb plots as the
default, type setoptions(dumbplot:T); 'dumb:F' will then be necessary to
get high resolution plots.  The default size of a dumb plot, including
labels, is M lines by N - 1 character positions, where M and N are the
values of options 'height' and 'width'.  You can override these defaults
by graphics keywords 'height' and 'width' whose values define M and/or
N.  See topics setoptions(), 'options' and 'graph_keys'.

@@@@specification_of_data
                  Specification of data to be plotted
Commands plot(), chplot(), lineplot(), stringplot(), addpoints(),
addlines(), addchars() and addstrings() all require arguments x and y
which specify plotting positions.  x is a REAL vector and y is a REAL
vector or matrix.  If y has more than 1 column, each column is plotted
against x.  For addstrings(), y must be a vector of the same length as
x.

Alternatively, arguments x and y can be replaced by a structure with at
least two REAL components.  For example, plot(structure(x,y)) is
equivalent to plot(x,y).  If there are more than two components, the
additional ones are ignored.  For example, plot(structure(x,y,
info:"Test Data")) is also equivalent to plot(x,y).

Except for stringplot() and addstrings(), x can be a scalar or a vector
of length 2 which implicitly specifies ny equally spaced values where ny
= nrows(y).  When x = x0 is a scalar x0, the implied vector is
vector(x0,x0+1,x0+2,...).  If x is vector(x0,dx), the implied vector is
vector(x0,x0+dx,x0+2*dx, ...).  Otherwise, x and y must have the same
number of rows.

For plot(), chplot(), and lineplot(), if x or y are specified as keyword
phrases, as in plot(Time:tm,Level:y), the keywords are used as axis
labels; however, keywords 'xlab' or 'ylab' (see below) will override the
name:x or name:y forms.  See topic 'graph_keys'.

@@@@examples_1#Examples
   plot(1,y) is short for plot(run(nrows(y)),y)
   plot(vector(1979,1/12),y) is short for
              plot(run(0,nrows(y)-1)/12+1979,y)
The second example might be used to plot monthly data starting January
1979 against time.

@@@@variable_LASTPLOT
                        GRAPH variable LASTPLOT
As a "side effect", all plotting commands create a GRAPH variable with
name LASTPLOT which encapulates all the information used to create the
plot.  The information is saved in a resolution independent form.  You
can assign LASTPLOT to another variable (for example, plot1 <- LASTPLOT)
or redisplay it, possibly with changed limits or labeling information,
using showplot().  You can print it (as a "dumb" plot) by
print(LASTPLOT) or write(LASTPLOT) or simply by typing LASTPLOT.

You can suppress the creation of LASTPLOT by keyword phrase 'keep:F'.
This might be useful if you were running out of memory.


@@@@GRAPHWINDOWS#Vaariable GRAPHWINDOWS
In addition, MacAnova maintains GRAPHWINDOWS, a special structure
variable, with one component for each possible graphics window (1
component in non-windowed versions).  Briefly, GRAPHWINDOWS[I]
(component I of GRAPHWINDOWS) is either a GRAPH variable encapsulating
the plot in graphics window I, or is NULL when there is no plot in
graphics window I.  See topic 'GRAPHWINDOWS'.

@@@@adding_to_plot
                      Adding information to a plot
Commands addpoints(), addchars(), addlines(), and addstrings() allow you
to display GRAPH variables with added information.  Alternatively and
equivalently, you can use the keyword phrase 'add:T' as an argument to
plot(), chplot(), lineplot() or stringplot().  If the first argument is
a GRAPH variable (for example, addlines(graph,x,y)), the plot combines
the information in the GRAPH variable with the new information provided.
Otherwise, the information in LASTPLOT is used.  In no case is any GRAPH
variable other than LASTPLOT changed.

If graph is a GRAPH variable, plot(graph,x,y), chplot(graph,x,y,
symbols:c) and lineplot(graph,x,y) are equivalent to addpoints(graph,
x,y), addchars(graph,x,y,symbols:c) and addlines(graph,x,y),
respectively.

To force recomputation of any of xmin, xmax, ymin or ymax to include all
data use keyword phrases xmin:?, xmax:?, ymin:?, or ymax:?.

To suppress immediate display of the graph, as when you are building a
complex graph in stages, use 'show:F' as an argument to each plotting
command.  When you are done, simply type showplot().  It is an error to
use both 'show:F' and 'keep:F'.

@@@@examples_2#Examples
  Cmd> plot(x,y,show:F); graphVar <- LASTPLOT
  Cmd> addpoints(3,4)  # or plot(3,4,add:T) or plot(LASTPLOT,3,4)
  Cmd> addpoints(graphVar,10,20,keep:F)#or plot(graphVar,10,20,keep:F)
  Cmd> showplot(xmin:0,xmax:0,ymin:0,ymax:0)
produces three plots.  The first and third are plots of y vs x with the
addition of a single point at x=3 and y=4, and the second is a plot of y
vs x with the addition of a point at x = 10 and y = 20.  MacAnova also
recomputes the extremes displayed for the third plot.  Because of
'keep:F' LASTPLOT is not updated after the second addpoints() command.

@@@@graph_windows
                             Graph Windows
On versions with windows, up to 24 windows are available for use by
plotting commands.  In addition, "Panel of Graphs" windows, containing
miniature replicas of up to four plots in their four corners are also
created.

The graph in the currently displayed window, including the panel
windows, may be saved to the Clipboard by selecting Copy from the Edit
menu, saved to a file by selecting Save Graph As... on the File menu,
or printed by selecting Print... on the File menu.

On any plotting command you can specify which window to draw in by
keyword phrase 'window:n', where 1 <= n <= 8.  Keyword phrase 'window:0'
means you want to reuse the most recently drawn window.  This is the
default on any plotting command adding information to a previous plot.
This is useful for displaying a sequence of related plots that differ in
the value of a parameter.  If 'window:n' is not used and a plot is not
being added to, the first unused window is selected, or if all windows
are in use, a message is printed.

@@@@pausing_between_plots
                         Pausing between plots
Keyword phrase 'pause:T' on any plotting command results in MacAnova
pausing after the plot is drawn.  This is particularly useful when
drawing repeated graphs in a 'for' or 'while' loop.  Keyword phrase
'pause:F' suppresses any such pause.  The default on windowed versions
is pause:F while under DOS or Unix/Linux it's pause:T.  On all machines,
the pause can be terminated by hitting RETURN.  You can use the File
and Edit menus to print the graph or to Copy the graph to the Clipboard.
Together with the window keyword, this permits you to display an
unlimited number of graphs successively in the same window, pausing
after each one to examine it and possibly print it or copy it.

@@@@plotting_in_unix_linux
                         Plotting on Unix/Linux
The nonwindowed version on Unix/Linux produces Tektronix-compatible
plotting sequences.  If MacAnova is running in a Xterm pseudo VT100
window, a pseudo Tektronix 4014 graphics window is opened and drawn to,
switching back to the VT100 window when done.

The CHARACTER strings which make up the value of option 'tekset' (see
subtopic 'options:"tekset"') are sent to the terminal to switch into and
out of Tektronix emulation mode.  MacAnova initializes the value of
'tekset' for Xterm, when that is appropriate.  Otherwise, the value of
'tekset' is intialized with strings that are recognized by Versaterm, a
Macintosh terminal emulator program.  When you are using some other
terminal emulator (such as DOS kermit or Macintosh NCSA Telnet) that
supports Tektronix 4014 plotting, you will need to set option 'tekset'
appropriately.  Some suggested values are given in topic 'options'.  See
also topics vt() and tek().
@@@@______

====GRAPHWINDOWS%#plotting,syntax
%%%%
Type help(GRAPHWINDOWS) for information on special variable GRAPHWINDOWS
Type help(graph_assign) for information on plotting by assigning to
  components of GRAPHWINDOWS
%%%%
@@@@introduction#Introduction
A special variable GRAPHWINDOWS is always defined in MacAnova.  It is a
structure (see topic 'structures') with a component for each possible
graphics window.  In the DOS version and non-windowed Unix/Linux
versions, GRAPHWINDOWS has only one component.

Each component of GRAPHWINDOWS is either a GRAPH variable or is NULL.
When it is a GRAPH variable, it encapsulates everything used to draw the
plot in the corresponding window (see topic 'variables').

In windowed versions, when you close a graphics window, the
corresponding component of GRAPHWINDOWS is set to NULL.

@@@@names_of_components#Names of components
The name of GRAPHWINDOWS[I] (component I of GRAPHWINDOWS), where I is a
positive integer, is one of the following:
   Name                 Meaning
  Empty_I       GRAPHWINDOWS[I] is NULL
  Graph_I       GRAPHWINDOWS[I] is a GRAPH variable
  LASTPLOT      GRAPHWINDOWS[I] is a GRAPH variable that is identical to
                GRAPH variable LASTPLOT which is normally created as a
                "side effect" every time a plot is drawn.

Thus
  Cmd> compnames(GRAPHWINDOWS)
summarizes the status of all the windows.  See compnames().

If the name of GRAPHWINDOWS[I] is LASTPLOT and you plot to window J !=
I, the name of GRAPHWINDOWS[I] is changed to Graph_I and GRAPHWINDOWS[J]
is given name LASTPLOT.

After a plotting command with keyword phrase 'keep:F', GRAPHWINDOWS[I]
becomes a NULL with name Empty_I.  If LASTPLOT exists, it doesn't
change.

When the name of GRAPHWINDOWS[I] is LASTPLOT, neither LASTPLOT <- var or
delete(LASTPLOT) affect the contents of GRAPHWINDOWS[I] but its name
automatically becomes Graph_I since it can no longer be guaranteed to be
the same as LASTPLOT.

@@@@deleting_GRAPHWINDOWS#Deleting GRAPHWINDOWS
delete(GRAPHWINDOWS) does not remove GRAPHWINDOWS but replaces all of
its components by NULL, without changing what is actually displayed in
any graphics window.  See delete().

@@@@assignment_to_GRAPHWINDOWS#Assignment to GRAPHWINDOWS
You can also assign to components of GRAPHWINDOWS.  For details see
topic 'graph_assign'.  Briefly, the behavior is as follows.

GRAPHWINDOWS[I] <- NULL makes component I of GRAPHWINDOWS NULL without
  changing what is displayed or affecting LASTPLOT.

GRAPHWINDOWS[I] <- graphVar, where graphVar is a GRAPH variable, makes
  GRAPHWINDOWS[I] identical to graphVar and displays its new contents in
  graphics window I.  GRAPH variable LASTPLOT is set identical to
  graphVar and GRAPHWINDOWS[I] is renamed LASTPLOT.

GRAPHWINDOWS[I] <- structure(graphics key words) modifies or replaces
  component GRAPHWINDOWS[I] and displays it in graphics window I.  GRAPH
  variable LASTPLOT is set identical to GRAPHWINDOWS[i] which is renamed
  LASTPLOT.

@@@@NULL_components#NULL components
GRAPHWINDOWS[I] can be NULL for one of three reasons: (a) Nothing has
been drawn in the window or it has been closed; (b) keyword phrase
'keep:F' was used when the graph in the window was drawn; or (c) the
graph variable has been cleared, either by delete(GRAPHWINDOWS) or by
GRAPHWINDOWS[I] <- NULL.

@@@@effect_of_save_and_restore#Effect of save() and restore()
By default, save() and asciisave() save GRAPHWINDOWS as part of the
saved workspace, although this can be suppressed by keyword phrase
'graphwind:F'.  When the saved workspace is restored, GRAPHWINDOWS is
restored.  In windowed versions, the restored graphs are redrawn,
replacing any existing graphs (see restore()).  The names of the
restored components are all either Empty_I or Graph_I, even if one of
the original components of GRAPHWINDOWS was named LASTPLOT.

@@@@see_also#Cross references
See topic 'graphs' and 'graph_keys' for general information about
plotting in MacAnova.
@@@@______

====graph_assign#plotting,syntax
%%%%
GRAPHWINDOWS[I] <- gVar, positive integer I, GRAPH variable gVar
GRAPHWINDOWS[I] <- structure(x:xvalues,y:yvalues [keyword phrases]),
  xvalues REAL vector, yvalues REAL vector or matrix
GRAPHWINDOWS[I] <- structure(x:xvalues,y:yvalues, symbols:ch\
  [, keyword phrases])
GRAPHWINDOWS[I] <- structure(x:xvalues,y:yvalues, lines:T\
  [, keyword phrases])
GRAPHWINDOWS[I] <- structure(x:xvalues,y:yvalues, strings:s\
  [, keyword phrases]), yvalues a REAL vector
GRAPHWINDOWS[I] <- structure(graphics keyword phrases without 'x', 'y')
GRAPHWINDOWS[I] <- NULL

Type help(GRAPHWINDOWS) for information on special variable GRAPHWINDOWS
%%%%
@@@@intoduction#Intoduction
This topic describes the effect of GRAPHWINDOWS[I] <- var, where
GRAPHWINDOWS is a special structure variable described in topic
'GRAPHWINDOWS'.

GRAPHWINDOWS[I], component I of GRAPHWINDOWS, is either a GRAPH variable
encapsulating all the information used to draw the plot in the I-th
graphics window or NULL.  You can draw, modify or label a plot in a
graphics window by GRAPHWINDOWS[I] <- var, where var is a GRAPH
variable, a structure or NULL.  This facility supplements the use of
plotting commands such as plot(), lineplot(), chplot(), stringplot() and
showplot().

In the following, I is an integer.  Currently in the windowed versions,
I must satisfy 1 <= I <= 8 and in the non-windowed versions I = 1.

@@@@assignment_of_NULL#Assignment of NULL
  Cmd> GRAPHWINDOWS[I] <- NULL
sets GRAPHWINDOWS[I] to NULL and renames the component "Empty_I".  If
GRAPHWINDOWS[I] contained a GRAPH variable, it is discarded.  This has
no effect on what, if anything, is displayed in graphics window I or on
the value of variable LASTPLOT if it exists.

@@@@assignment_of_graph_variable#Assignment of graph variable
  Cmd> GRAPHWINDOWS[I] <- graphVar
graphVar a GRAPH variable, displays the plot in graphics window I and
then makes both GRAPHWINDOWS[I] and LASTPLOT identical to graphVar.
That is, it does the same as showplot(graphVar, window:I) (simply
showplot(graphVar) in non-windowed versions).  Moreover, GRAPHWINDOWS[I]
is renamed LASTPLOT.

@@@@assignment_of_structure#Assignment of structure
  Cmd> GRAPHWINDOWS[I] <- Str
where Str is a structure, can duplicate the behavior of plot(),
lineplot(..., window:I), chplot(..., window:I), stringplot(...,
window:I) and showplot(..., window:I).  Str must contain at least one
component whose name is the same as a graphics keyword (see topic
'graph_keys') and such keyword phrases determine what happens.  Any
components with graphics keyword names must have the same types of
values as the corresponding keyword.  For example, a component named
'lines' must be a LOGICAL scalar, T or F and a component 'x' must be a
REAL vector.

Str may always include components names 'x', 'y', 'xlab', 'ylab' and
'title', as well 'ticks', 'border', 'xticks', 'yticks', 'xticklen',
'yticklen', 'xticklabs' and 'yticklabs'.  When 'x' and 'y' are
components, Str may also have component 'add'.  Components 'keep' and
'show' are allowed but must have value True.  If Str has component
'window', its value must be I.  You may not use 'file' or other keywords
related to files as component names.

If Str does not have components 'x' and 'y', the assignment behaves like
showplot() and Str should not have components 'lines', 'linetype',
'thickness', 'impulses', or 'add'.

If Str has components 'x', 'y' and 'symbols', the assignment behaves
like chplot().  With 'add:T', it behaves like addchars().  Str can also
have components 'lines', 'linetype', 'thickness' and 'impulses'.

If Str has components 'x', 'y' and 'strings', the assignment behaves
like stringplot().  With 'add:T', it behaves like addstrings().  Str
must not have components 'lines', 'linetype', 'thickness' or 'impulses'.

If Str has components 'x', 'y' and 'lines' but not 'symbols', the
assignment behaves like lineplot().  With 'add:T', it behaves like
addlines().

If Str has components 'x' and 'y', but not 'symbols', 'strings' or
'lines', the assignment behaves like plot().  With 'add:T', it behaves
like addpoints().  Str can also have component 'impulses' but not
'linetype' or 'thickness'.

@@@@use_of_mouse#Use of mouse
In some versions, you can use Mouse() to create Str with coordinates
taken interactively from a graphics window.  See Mouse() for details.

@@@@examples#Examples
Examples:
  Cmd> GRAPHWINDOWS[3] <- structure(x:temp, y:percent, lines:T,\
    symbols:"\1", xlab:"Temperature", ylab:"Percent")

does the same as

  Cmd> lineplot(temp, percent, lines:T, symbols:"\1",window:3,\
    xlab:"Temperature", ylab:"Percent")

Both also create GRAPH variable LASTPLOT which is identical to
GRAPHWINDOWS[3].

  Cmd> GRAPHWINDOWS[4] <- graphVar # GRAPH variable graphVar

does the same as

  Cmd> showplot(graphVar, window:4)

LASTPLOT is created identical to graphVar and GRAPHWINDOWS[4].

  Cmd> GRAPHWINDOWS[1] <- structure(x:17.3, y:25, add:T,\
    strings:"Observations made July 3, 1998", justify:"l")

does the same as

  Cmd> stringplot(GRAPHWINDOWS[1], 17.3, 25, add:T, window:1,\
    strings:"Observations made July 3, 1998", justify:"l")

In some versions
  Cmd> stuff <- Mouse(lines:T,n:10);GRAPHWINDOWS[stuff$window] <- stuff

plots a segmented line with 10 segments with the end and join points
specified by clicking in a graphics window with the mouse.

@@@@see_also#Cross references
See also topics 'graphs', 'graph_keys', plot(), lineplot(), chplot(),
stringplot(), showplot(), addpoints(), addchars(), and addstrings().
@@@@______

====graph_border#plotting,files,output
%%%%
Graphics keyword phrase 'borders:word' controls on which sides of a
  graph borders should be drawn. Possible values for 'word' are "all",
  "none" or some combination of "B", "L", "T", and "R" or their lower
  case counterparts.
%%%%
@@@@specifying_borders#Specifying borders
By default, borders are drawn on all four sides of a graph, providing a
rectangular frame.  You can modify this behavior using graphics keyword
phrase 'borders:word', where word is a quoted string or character
scalar.  If word isn't "all" (the default) or "none", it must contain
only the characters 'B' (bottom), 'L' (left), 'T' (top) or 'R' (right),
or their lower case counterparts 'b', 'l', 't' and 'r'.  Value "" is
equivalent to "none".

Keyword phrase 'borders:word' also sets the edges where tick marks will
be drawn, unless 'ticks:word' is also an argument.  See topic
'graph_ticks'.

@@@@examples#Examples
Examples:
  Cmd> plot(x,y,borders:"LB") # or plot(x,y,borders:"lb")
This produces a plot with border and ticks drawn only at left and
bottom.

  Cmd> plot(x,y,borders:"none") # or plot(x,y,borders:"")
This produces a plot with no border or ticks drawn.
@@@@______

====graph_files%#plotting,files,output
%%%%
Type help(graph_files) for information on saving plots in files.
%%%%
@@@@introduction#Introduction
This topic summarizes those plotting options allowing you to save a plot
in a file.  See also topics 'graphs', 'graph_keys', 'files'.

@@@@file_keyword#Keyword 'file'
When keyword phrase file:FileName is an argument to a plotting command,
no plot is displayed.  Instead, PostScript commands for the new plot are
written to file FileName, which must be a CHARACTER scalar or string.
If keyword phrase landscape:T is also present, the plot will be rotated
to fill an 8.5" by 11" page.  If option 'dumbplot' has been set to True
(see subtopic 'options:"dumbplot"'), you will need to put dumb:F to get
a PostScript file.

With file:fileName, if keyword phrase dumb:T or ps:F is also an
argument, a low resolution "dumb" plot is written rather than
PostScript.  This consists only of characters that can be printed on any
printer.  On some systems, if ps:F appears and dumb:T does not, the plot
is written in a binary form appropriate to the platform (Tektronix
commands on Unix/Linux; PICT format on Mac OS 9).

If the keyword phrase 'new:T' is an argument, the information in the
file is destroyed before the plotting commands are written.  Otherwise,
information is added at the end of the file.  It formerly was the case
tha a PostScript "prolog" was written only with new:T but now a prolog
is always written before PostScript commands.

@@@@encapsulated_postscript#Encapsulated postscript
On Mac OS 9 you can write the plot as an encapsulated PostScript file
by using 'epsf:T, file:fileName'.  The file can be imported into some
word-processors and graphics editing programs.  epsf:T is illegal with
new:F or ps:F.

@@@@binary_formatted_files#Binary formatted files
On Mac OS 9 and in the DOS extended memory version you can write a
binary version of the plot to a file using keyword phrase
screendump:fileName.  The format used is one appropriate to the
computer.  The Mac OS 9 version writes a so called PICT file and the
extended memory DOS version writes a PCX file.  'screendump:fileName' is
not legal together with dumb:T or file:FileName.

On Mac OS 9, item Save Graph As on the File menu writes the graph
window currently being displayed as a PICT file.

@@@@see_also#Cross references
See topics 'data_files', 'matread_file', 'vecread_file' and
'macro_files' for information on files containing sets and macros.
@@@@______

====graph_keys#plotting
%%%%
List of keywords which can be used on some or all graphing commands or
to name a component of the value of graphics keyword 'keys'.
 Keyword               Value
 add                   T or F
 borders               "all", "none" or combination of "B","L","T","R"
 dumb                  T or F
 epsf                  T or F
 file                  CHARACTER scalar file name
 height                Integer >= 12
 impulse               T or F
 keep                  F or T
 keys                  structure with graphics keyword component names
 landscape             T or F
 lines                 T or F
 linetype              Integer between -99 and 99
 logx                  T or F
 logy                  T or F
 new                   T or F
 notes                 CHARACTER vector
 pause                 T or F
 ps                    F or T
 screendump            CHARACTER scalar file name
 show                  F or T
 silent                F or T
 strings               CHARACTER scalar or vector
 symbols               CHARACTER or integer scalar, vector or matrix
 thickness             REAL scalar between .1 and 10
 ticks                 "all", "none" or combination of "B","L","T","R"
 title                 CHARACTER scalar (<= 75 characters)
 width                 Integer >= 30
 window                Integer between 0 and 8
 x                     REAL vector or NULL (only in 'keys')
 xaxis                 F or T
 xlab                  CHARACTER scalar (<= 50 characters)
 xmax                  REAL scalar or ?
 xmin                  REAL scalar or ?
 xticklabs             CHARACTER vector
 xticklen:             REAL scalar >= -1
 xticks                REAL vector, ? or NULL
 y                     REAL vector or matrix or NULL (only in 'keys')
 yaxis                 F or T
 ylab                  CHARACTER scalar (<= 20 characters)
 ymax                  REAL scalar or ?
 ymin                  REAL scalar or ?
 yticklabs             CHARACTER vector
 yticklen              REAL scalar >= -1
 yticks                REAL vector, ? or NULL

Topic 'graphs' has general information on making graphs.
%%%%
Here is a summary of the optional keyword phrase arguments recognized by
most plotting commands.  See also topics 'graphs', 'graph_files',
'keywords', 'graph_assign'.  You can get a list of all the keywords with
their permissible values by typing 'usage(graph_keys)'.

After the list of keywords there are specific descriptions of the use of
'add:T', 'keys:Str' and GRAPHWINDOWS[i] <- structure(...) with structure
components named using graphics keywords.

                      Catalog of graphics keywords
     Keyword Phrase                   Description
@@@@x
 x:xdata *                            xdata a REAL vector specifying
                                      data for x-axis or NULL
@@@@y
 y:ydata *                            ydata a REAL vector or matrix
                                      specifying data for y-axis or NULL
@@@@symbols
 symbols:symVar                       symVar a CHARACTER or integer
                                      scalar, vector or matrix
                                      specifying plotting symbols;
                                      symVar = "###" means use row or
                                      column number as plotting symbol
@@@@strings
 strings:charVar                      charVar a CHARACTER scalar or
                                      vector specifying labelling
                                      information to be plotted at
                                      positions specified by x and y.
@@@@keys1
 keys:Str                             Str a structure with names
                                      matching other graphics keywords;
                                      see below.
@@@@add1
 add:T                                Combine the information in the
                                      current plotting command with
                                      information in LASTPLOT (or a
                                      GRAPH variable argument) to create
                                      a new graph; see below.
@@@@title
 title:"Plot title of your choice"    (up to 75 characters)
@@@@xlab
 xlab:"X-axis label"                  (up to 50 characters)
@@@@ylab
 ylab:"Y-axis label"                  (up to 20 characters)
@@@@xyminmax
 xmin:xMinVal or xmin:?               Minimum and maximum values for
 xmax:xMaxVal or xmax:?               x-axis and y-axis.  Value ?
 ymin:yMinVal or ymin:?               means compute from new data and
 ymax:yMaxVal or ymax:?               any data in graph being modified.
@@@@logx
 logx:T                               Use log scale for x-axis
@@@@logy
 logy:T                               Use log scale for y-axis
@@@@xaxis
 xaxis:F                              Do not draw x axis (line y = 0).
@@@@yaxis
 yaxis:F                              Do not draw y axis (line x = 0).
@@@@borders
 borders:Word                         Controls which sides of the graph
                                      borders will be drawn.  Word can
                                      be "all", "none", "", or a
                                      combination of one or more of "B",
                                      "b", "L", "l", "T", "t", "R", "r".
                                      See topic 'graph_border'.
@@@@ticks
 ticks:Word                           Controls which sides of the
                                      graph will have tick marks.  Word
                                      has same form as for 'borders'.
                                      See topic 'graph_ticks'.
@@@@xyticks
 xticks:RealVec                       Locations for x- or y-axis tick
 yticks:RealVec                       marks and labels. xticks:? and
                                      yticks:? mean compute from data.
                                      xticks:NULL and yticks:NULL mean
                                      no tick marks or labels.  See
                                      topic 'graph_ticks'
@@@@xyticklabs
 xticklabs:CharVec                    Labels for x-axis or y-axis tick
 yticklabs:CharVec                    locations.  Permissible only with
                                      custom tick positions and when
                                      length(CharVec) = number of ticks.
                                      See topic 'graph_ticks'
@@@@xyticklen
 xticklen:length                      Length of x- or y-axis ticks.
 yticklen:length                      Value length >= -1.  length < 0
                                      means outside frame; length > 2
                                      means full gridline.  Defaults are
                                      .5
@@@@lines
 lines:T                              On all plotting commands except
                                      boxplot(), stringplot() and
                                      addstrings(), connect successive
                                      points with lines.
 lines:F                              Suppress drawing lines on
                                      lineplot() and addlines().
@@@@linetype
 linetype:n                           On lineplot() and other commands
                                      with lines:T sets the line type to
                                      n, default is 1 (solid line).  n
                                      must be an integer -100 < n < 100.
                                      n < 0 is the same as abs(n) except
                                      no warning is printed when lines
                                      are not being drawn; n = 0 is the
                                      same as n = -1
@@@@thickness
 thickness:W                          On lineplot() and other commands
                                      with lines:T sets the line
                                      thickness to W times normal
                                      thickness, default = 1.  W must be
                                      between .1 and 10.  Has no effect
                                      when not feasible as with dumb:T.
@@@@impulse
 impulse:T                            On all plotting commands except
                                      boxplot(), stringplot() and
                                      addstrings(), draw line from
                                      x-axis (y=0 line) to points.
@@@@show
 show:F                               Do not display plot, only save as
                                      LASTPLOT but not in GRAPHWINDOWS
@@@@keep
 keep:F                               Do not save plot as LASTPLOT or in
                                      GRAPHWINDOWS; only display.  The
                                      corresponding component of
                                      GRAPHWINDOWS is cleared unless
                                      show:F is an argument.
@@@@dumb
 dumb:T                               Make low resolution plot using
                                      printable characters only,
                                      suitable for printing on a line
                                      printer.  Default is taken from
                                      option 'dumbplot'; F means high
                                      resolution.
@@@@height
 height:n                             Number of lines to be used in
                                      "dumb" plot; n >= 12 is required;
                                      ignored without dumb:T.
@@@@width
 width:n                              Width in character positions to be
                                      used in "dumb" plot; n >= 30 is
                                      required; ignored without dumb:T.
@@@@window
 window:n                             Draw plot in window n (1 <= n <=
                                      8).  (versions with windows only)
                                      If n = 0, use window most recently
                                      used.
@@@@pause
 pause:T (versions with windows)      Forces (T) or suppresses (F) a
 pause:F (other versions)             pause after the graph is drawn.
@@@@file
 file:FileName                        Write PostScript to file Filename
@@@@new
 new:T                                Clear file FileName before writing
@@@@landscape
 landscape:T                          PostScript plot will be rotated so
                                      as to fill 8.5" by 11" page.
@@@@ps
 ps:F                                 Suppresses PostScript when
                                      writing a plot to a file.  On
                                      Unix/Linux, Tektronix plotting
                                      commands are written.  On 
                                      Mac OS 9, a PICT file is written.
                                      On other systems, a 'dumb' plot is
                                      written.
@@@@epsf
 epsf:T (Mac OS 9 only)               Produces an encapsulated
                                      PostScript file.  Legal only with
                                      file:fileName.
@@@@silent
 silent:T                             Suppress warning messages
@@@@screendump
 screendump:FileName                  Save a copy of screen in file
 (Mac OS 9  and DOS extended memory   FileName in a form other
 versions only)                       applications may be able to
                                      import.
@@@@notes
 notes:charVec                        Adds notes to GRAPH symbol
                                      LASTPLOT ; charVec must be a
                                      CHARACTER vector or scalar.  See
                                      topic 'notes'.
@@@@______
* 'x' and 'y' have no special meaning as keywords but have meaning as
component names of the value of keyword 'keys' when it is an argument.
See below.

@@@@add2
                     Use of keyword phrase 'add:T'
When keyword phrase 'add:T' is an argument to plot(), chplot(),
lineplot() or stringplot(), it makes them behave like addpoints(),
addchars(), addlines() and addstrings(), respectively.  'add' may not be
used without new data, so it is illegal with showplot().  Conversely,
use of 'add:F' on addpoints(), addchars(), addlines() or addstrings()
makes them behave like plot(), chplot(), lineplot() or stringplot().

@@@@keys2
                    Use of keyword phrase 'keys:Str'
The various graphics keyword phrases are usually used as separate
arguments to plotting commands.  Instead you can specify them by
argument keys:Str, where Str is a structure with components with names
matching graphics keywords.  With this usage, no graphics keyword
phrases except keys:Str can be arguments.  In addition to the regular
graphics keyword names such as 'xlab' and 'ticks', you can use names 'x'
and 'y' to specify components of Str which provide data to plot.

This is probably best illustrated by example.  The following lines are
equivalent.

  Cmd> plot(time,d,xmin:0,ymin:0,xlab:"Time",ylab:"Distance")

  Cmd> plot(time,d,keys:structure(xmin:0,ymin:0,xlab:"Time",\
       ylab:"Distance"))

  Cmd> plot(keys:structure(x:time,y:d,xmin:0,ymin:0,xlab:"Time",\
       ylab:"Distance"))

The following is illegal because it mixes use of 'keys' with graphics
keywords 'xlab' and 'ylab' outside the structure.

  Cmd> plot(time,d,keys:structure(xmin:0,ymin:0), xlab:"Time",\
       ylab:"Distance") # xlab & ylab are not in the structure

@@@@assignment_to_GRAPHWINDOWS
         Use of keywords with GRAPHWINDOWS[I] <- structure(...)

Many of the graphics keywords can be used to define the components of a
structure being assigned to GRAPHWINDOWS[I].  For example,

  Cmd> GRAPHWINDOWS[3] <- structure(x:time,y:d,lines:T,xlab:"Time",\
       ylab:"Distance")

has the same effect as

  Cmd> lineplot(time,d,window:3,xlab:"Time", ylab:"Distance").

The structure being assigned to GRAPHWINDOWS[I] must not have components
named 'file', 'new', 'landscape', 'ps', 'epsf' or 'screendump'.  If
there are components named 'keep' and/or 'show' they must have value
True.  In windowed versions, the structure should not have components
'dumb', 'height' or 'width'.  If there is a component named 'windows',
its value must be the same as I.  If either component 'x' or 'y' is
NULL, GRAPHWINDOWS[I] is unchanged.

See topics 'GRAPHWINDOWS' and 'graph_assign' for more details
@@@@______

====graph_ticks#plotting
%%%%
Graphics keywords 'xticks', 'yticks', 'xticklen', 'yticklen', 'ticks',
  'xticklabs', 'yticklabs' are used to modify default tick marks in
  graphs, provide labels for them and specify which sides of a plot they
  are drawn.
Values for 'xticks' and 'yticks' are REAL vectors or NULL.
Values for 'xticklen' and 'ytick' length are REAL scalars >= -1.
Values for 'ticks' must be "all", "none" or a combination of letters 'B"
  (bottom), 'L' (left), 'T' (top) and 'R' (right) or their lower case
  counterparts.
Values for 'xticklabs' and 'yticklabs' must be CHARACTER vectors, ?, or
  NULL
%%%%
@@@@introduction#Introduction
This topic summarizes how you can customize tick positions, appearance
and labelling on graphs.  See topic 'graphs' for general information on
plotting commands and topic 'graph_keys' for information about keyword
phrases.

By default, plotting commands draw tick marks at automatically computed
"neat" positions.  The default tick length is about half the width of a
character.  All tick marks are labeled in the left or bottom margin,
with the default labels being their locations.

@@@@setting_tick_positions#Setting tick positions
You can customize the horizontal and vertical positions of tick marks by
keywords 'xticks' and 'yticks' whose values must be REAL vectors or
NULL.  xticks:NULL and yticks:NULL suppress ticks and their labels
entirely.  xticks:? or yticks:? cause the default tick mark positions to
be used.

@@@@setting_tick_lengths#Setting tick lengths
You can control the lengths of the tick marks by keywords 'xticklen' and
'yticklen' whose values should be REAL scalars >= -1.  The default
length correspondes to xticklen:.5 and yticklen:.5.  Values < 0 give
ticks outside the border and 0 values suppress drawing ticks but not
their labels.  Values > 2 cause full gridlines from one side of the plot
to the other to be drawn.

@@@@setting_borders_with_ticks#Setting borders with ticks
By default, tick marks are drawn on any edge of the graph where a border
line is drawn, with full gridlines drawn if a border is drawn at either
end of the line.  You can modify this behavior using 'ticks:word', where
'word' is a quoted string or character scalar.  If 'word' isn't "all" or
"none", it must contain only the characters 'B' (bottom), 'L' (left),
'T' (top) or 'R' (right), or their lower case counterparts 'b', 'l', 't'
and 'r'.  Value "" is equivalent to "none".

Using 'borders:word' without 'ticks' automatically sets the sides where
ticks are drawn to match where borders are drawn.  See topic
'graph_border'.

Regardless of the value of 'ticks', tick labels will always be put at
the bottom and left.

@@@@setting_character_tick_labels#Setting character tick labels
You can replace numerical labels for ticks with arbitrary labels using
keyword phrases 'xticklabs:charvec' and/or 'yticklabs:charvec', where
charvec is a CHARACTER vector.  This is permissible only in the
following situations (described for the x-axis).

 Keyword phrase 'xticks:realvec' is an argument and length(charvec) =
 length(charvec) = length(realvec).

 You are displaying or adding to a existing plot for which x-axis tick
 positions were supplied and length(charvec) = number of such positions.

 You are labelling the "box number" axis on a box plot and
 length(realvec) = number of boxes.

In particular, 'xticklabs' is ignored if default tick positions are
being used, even when charvec is of the right length.

@@@@examples#Examples
Examples:
  Cmd> plot(x,y,xticks:vector(1,2,4),yticks:NULL,xticklen:1.5,\
   ticks:"B", xticklabs:vector("Fair", "OK", "Super"))

gives x-axis ticks 1.5 times the width of a character (3 times normal)
at x = 1, 2 and 4 on the bottom border only, giving them special labels,
and suppresses all y-axis ticks and their labels.

  Cmd> plot(x,y,xticklen:3,yticklen:-.5, ticks:"BL")
draws full gridlines perpendicular to the x-axis and default length
ticks along the outside of the left edge of the frame.  With ticks:"L",
ticks:"R", ticks:"LR" or ticks:"none", the gridlines would not be drawn
at all.

  Cmd> showplot(xticks:?,yticks:?)
sets the default tick positions, without altering their length.  If
custom tick labels were set, they are discarded.  Use of 'xticklabs' or
'yticklabs' produces a warning message but has no other effect.

@@@@see_also#Cross references
See also topics 'graphs' and 'graph_keys'.
@@@@______

====halfnorm()#transformations,descriptive statistics,ordering
%%%%
halfnorm(x [,ties:"ignore" or "average" or "minimum"]), x REAL or a
  structure with REAL components.
halfnorm(n:N), integer N > 0.
%%%%
@@@@usage#Usage
halfnorm(x) computes the vector of approximate half normal scores for
the data in the REAL vector x.  This probably makes sense only when the
elements of x are all non-negative, although that is not required.

halfnorm(n:N), N a positive integer, is equivalent to halfnorm(run(N)).

What is computed is equivalent to
   invnor(.5 + .5*(rank(abs(x),ties:"ignore") - .375)/(n + .25))
where n is the number of non-MISSING values.  The value corresponding to
a missing value is MISSING.

The most important use of halfnorm() is probably plot(halfnorm(ss),
sqrt(ss)), where ss is a vector of 1 degree of freedom sums of squares.
This produces a half normal plot of sqrt(ss).

halfnorm(x [keywords]) has the same labels as x, if any.

@@@@ties_keyword#Keyword 'ties'
halfnorm(x,ties:Method), where Method is "ignore", "average", or
"minimum" (or "i", "a", "m") computes invnor(.5 +
.5*(rank(abs(x),ties:Method) - .375)/(n + .25)).  See rank() for a
detailed discussion of the three methods.  It is hard to think of a
situation when you would want to use "minimum" with halfnorm().

@@@@matrix_or_array_structure_argument#Matrix or array structure argument
If x is a matrix, the result is a matrix each of whose columns contains
the half normal scores for the corresponding column of x.

If x is an array, halfnorm(x) is an array of the same size and shape
with all the elements with fixed values of subscripts 2, 3, ... defining
a "column" whose half normal scores are computed.  An array with
dimension > 2 is always treated as an array and not as a matrix, even if
there are at most two dimensions greater than 1.

It is also acceptable for x to be a structure, whose non-structure
components are all REAL.  In that case, halfnorm(x) returns a structure
of the same form, each of whose non-structure components is the result
of applying halfnorm() to the corresponding component of x.

@@@@example#Example
Example:
  Cmd> x <- vector(.59,8.82,9.46,3.34,3.49) # ranks are 1,4,5,2,3

  Cmd> halfnorm(x)
  (1)     0.14976      1.0162      1.5588     0.39821     0.67449

@@@@see_also#Cross references
See also rankits().
@@@@______

====haslabels()#general,variables
%%%%
haslabels(x), x a variable that is not NULL.
%%%%
@@@@usage_with_example#Usage with example
haslabels(x) is True if and only if variable x has coordinate labels.

Example;
  Cmd> x <- yourMacro(y)
  Cmd> if (haslabels(y)){
        x <- matrix(x,labels:structure("",getlabels(y,2)))}

@@@@see_also#Cross references
See topics 'labels', getlabels().
@@@@______

haslabels() is implemented as a pre-defined macro.

====hasnotes()#general,variables
%%%%
hasnotes(x), x a variable that is not NULL.
%%%%
@@@@usage_with_example#Usage with example
hasnotes(x) is True if and only if variable x has attached notes.

Example:
  Cmd> x <- yourMacro(y)

  Cmd> if (hasnotes(y)){attachnotes(x, getnotes(y))}

@@@@see_also#Cross references
See topics 'notes', getnotes(), attachnotes(), appendnotes().
@@@@______

hasnotes() is implemented as a pre-defined macro.

====hconcat()#combining variables,variables,null variables
%%%%
hconcat(a,b,c,... [,labels:structure(rowLabs,colLabs), silent:T]) where
  a, b, c, ... matrices and rowLabs and colLabs are CHARACTER scalars or
  vectors
%%%%
@@@@usage#Usage
hconcat(a,b,c,...) combines matrices a, b, c ... side to side by
concatenating their rows.

All arguments must be of the same type, REAL, LOGICAL, or CHARACTER, and
have the same number of rows m.  The result is a matrix of that type
with m rows and na+nb+nc+... columns, where na, nb, nc, ... are the
number of columns of a, b, c, ... .


An argument that is a vector of length m is considered to be a m by 1
matrix.  In particular, if a is a vector of length m, hconcat(a) is a m
by 1 matrix.

An argument that is an array with only two dimensions not equal to 1 is
considered to be a matrix (see 'matrices').  For example,
  Cmd> hconcat(array(run(6),1,2,3),array(2*run(8),2,1,4))
is equivalent to
  Cmd> hconcat(matrix(run(6),2),matrix(2*run(8),2))

If a is a vector of length n, hconcat(a) is a matrix with n rows and 1
column.

Any argument of type NULL is ignored.  If all arguments are NULL, so is
the result.

@@@@labels_keyword#Keyword 'labels'
hconcat(a,b,...,labels:structure(rowLabs,colLabs) [,silent:T]) uses
CHARACTER scalars or vectors rowLabs and colLabs as row and column
labels for the result.  With silent:T, no warning is printed if labels
are the wrong size.  See topic 'labels' for details.

@@@@see_also#Cross references
See also topics vconcat(), vector(), 'matrices', 'NULL', 'vectors'.
@@@@______

====hconj()#time series,complex arithmetic
%%%%
hconj(hx), hx a REAL matrix representing complex data with Hermitian
  symmetry
%%%%
@@@@usage#Usage
hconj(hx) returns the complex conjugate (in packed Hermitian form) of
the columns of the vector or matrix hx, considered as complex series
with Hermitian symmetry in packed Hermitian form.

@@@@see_also#Cross references
See also cconj(), hreal(), himag(), creal(), cimag().

See topic 'complex' for discussion of complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====hdivh()#time series,complex arithmetic
%%%%
hdivh(hx1 [, hx2]), hx1 and hx2 REAL matrices representing complex data
  with Hermitian symmetry
%%%%
@@@@usage#Usage
hdivh(hx1, hx2) computes the element-wise complex ratio of elements in
the columns of REAL matrices or vectors hx1 and hx2, considered as
complex matrices in packed Hermitian form.  The result is also a complex
matrix in packed Hermitian form.

Any ratio of the form (0 + 0i)/(0 + 0i) is returned as 0 + 0i.  The ratio
of a non-zero element of cx1 and 0 + 0i is MISSING + MISSING*i.

When hx1 represents a single complex series (has 1 column), that series
is divided by all the series in hx2.  Similarly when hx2 represents a
single complex series, all the series in hx1 are divided by hx2.

For example, if hx1 is m by 1 and hx2 is m by 3, hdivh(hx1,hx2) is
equivalent to hdivh(hconcat(hx1,hx1,hx1),hx2).

hdivh(hx) is equivalent to hdivh(hx,hx) and yields a result with all
real parts = 1 and all imaginary parts = 0 (except (0 + 0i)/(0 + 0i)
elements).

@@@@see_also#Cross references
See also hdivhj(), cdivc(), cdivcj(), hprdh(), hprdhj(), cprdc(), cprdcj().

See topic 'complex' for discussion of complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====hdivhj()#time series,complex arithmetic
%%%%
hdivhj(hx1 [, hx2]), hx1 and hx2 REAL matrices representing complex data
  with Hermitian symmetry
%%%%
@@@@usage#Usage
hdivhj(hx1, hx2) computes the element-wise complex ratio of elements
in the columns of hx1 and hconj(hx2), considered as complex matrices in
packed Hermitian form.  The result is also a complex matrix in packed
Hermitian form.

Any ratio of the form (0 + 0i)/(0 + 0i) is returned as 0 + 0i.  The ratio
of a non-zero element of cx1 and 0 + 0i is MISSING + MISSING*i.

When hx1 represents a single complex series (has 1 column), that series
is divided by all the complex conjugates of the series in hx2.
Similarly, when hx2 represents a single complex series, all the series in
hx1 are divided by hconj(hx1).

For example, if hx1 is m by 1 and hx2 is m by 3, hdivhj(hx1,hx2) is
equivalent to hdivhj(hconcat(hx1,hx1,hx1),hx2).

hdivhj(hx) is equivalent to hdivhj(hx,hx).

@@@@see_also#Cross references
See also hdivh(), cdivc(), cdivcj(), hprdh(), hprdhj(), cprdc(),
cprdcj(), hconj().

See topic 'complex' for discussion of complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.

@@@@______

====help()#general
%%%%
help(topic [, allfiles:T])
help(topic1, topic2, ... [, allfiles:F])
help(Topic:Subtopics), Topic the name of a topic, Subtopics a CHARACTER
  scalar or vector naming subtopics of Topic
help(Topic, subtopic:Subtopics)
help(Topic, subtopic:"?")
help(index:helpfilename), CHARACTER scalar helpfilename
help(Pattern) where Pattern has form "start*", "start*end", or "*mid*",
  "start*mid*", ...
help(news [,allfiles:T]), help(news:yymmdd1 [,allfiles:T]) or
  help(news:vector(yymmdd1, yymmdd2) [,allfiles:T]), where yymmdd1 and
  yymmdd2 are integers like 990103, 19990103, 000717 or 20000727
help(key:KeyName [keywords]), where KeyName is a CHARACTER scalar or
  "?" (scans only current help file)
help(topic [,subtopic:Subtopics] , file:fileName or orig:T or alt:T),
  CHARACTER scalar fileName (scans only one help file)
%%%%
@@@@usage#Usage
help() with no argument will print a short message giving some of the
help() and gethelp() options.

help(topicname) and help("topicname") lists help information on the
named topic.

help(topicname, subtopic:"subtopic_name") does the same, but lists only
the information in the named subtopic.  If topicname has no more than 10
characters, help(topicname:"subtopic_name") does the same.

You can print several subtopics by, for example, help(topicname,
subtopic:vector("usage", "examples")).

help() returns an "invisible" LOGICAL scalar whose value is True only
when at least one topic requested was found.  The value may be assigned
or tested but will not be printed automatically.  See topic
'variables:"invisible"'.

Files named in pre-defined CHARACTER vector HELPFILES are searched until
the topic is found.  This is done by repeated calls to gethelp(), which
scans only one file at a time.

By default, when help is requested on only one topic, the search stops
the first time the topic is found in a file.  To force scanning all
files, use keyword phrase 'allfiles:T'.

help(topic1, topic2, ...) requests help on several topics at once.  You
cannot use keyword 'subtopic' when there is more than one topic, but any
argument can be of the form topicname:"subtopic_name".

In this case, by default, all the help files are scanned, which can take
a noticable time.  If you know all the topics are in a single file, you
can save a little waiting time by using 'allfiles:F' as an argument.

@@@@index_topics#Index topics
help(index:helpfilename), where helpfilename is a quoted string or
CHARACTER scalar identifying one of the help files named in HELPFILES
prints the index topic in that file.  In particular,
  Cmd> help(index:HELPFILES[3])
prints the index of the file whose name is in the third element of
HELPFILES.

If helpfilename doesn't exactly match any name in HELPFILES (ignoring
case), various matches are attempted using the wild card characters '*'
and '?'.  Thus help(index:"design.hlp") and help(index:"design") both
print the annotated index of design.hlp.

No other arguments or keywords can be used with 'index'.

@@@@examples#Examples
Examples:
  Cmd> help(anova); help(macros); help("break")
  Cmd> help(break); help(transformations) #now work; previously didn't
  Cmd> help(regress, usage:T) # same as usage(regress)
  Cmd> help(stepsetup, subtopic:"example")# or help(stepsetup:"example")
  Cmd> help(tsplot:vector("usage","example"))
  Cmd> if (!help(foo,silent:T)){print("No help on topic foo")}
  Cmd> help(index:"math")

@@@@resetting_current_help_file#Resetting current help file
You can reset the current help file to any particular file in HELPFILES
by
  Cmd> help(file:HELPFILES[I]) # 1 <= I <= length(HELPFILES)

On other usages of help(), the current help file is either not changed
or is changed to the last file searched.

  When no help is found or when there are several topics without all:F,
  the current help file is not changed.

  When there are several topics with all:F or a single topic, and at
  least one topic is found, the file containing the found topic becomes
  the current help file.

  Regardless of the number of topics, when reset:T is an argument, the
  current help file is not changed.

@@@@news_topic
                              Topic 'news'
help(news) lists in reverse chronological order news items about
MacAnova starting with the most recent entry back for three months.

help(news:vector(Date1,Date2) [,scrollback:T] [,all:T]), where Date1
and Date2 are numbers of the form yymmdd or yyyymmdd, lists in reverse
chronological order news items about MacAnova development dated between
Date1 and Date2.  For example, help(news:vector(991201,0000131)) and
help(news:vector(19991201,20001230)) list all news items dated in
December, 1999 or January, 2000

help(news:Date) lists all news items on or after Date.  For example,
help(news:000101) and help(news:200000100) list all news items on or
after January 1, 2000.

help(news:0) lists all available news items.  This will produce many of
lines of output and is not recommended.

You can use 'scrollback:T' with all these ways to read news topics.

By default, when looking for news topics, only file HELPFILES[1]
(usually "macanova.hlp") is scanned.  If you include 'all:T' as an
argument, all files in HELPFILES are searched for news items.

@@@@HELPFILES#Variable HELPFILES
HELPFILES is a CHARACTER vector initialized when MacAnova starts up to
contain all the standard help files except "userfun.hlp".

help() uses HELPFILES as a "circular" list.  If the current help file is
in the list, than the search starts with that file and wraps back to
HELPFILES[1] if necessary.  If the current help file is not in that
list, then the current help file is scanned, followed by the files named
in HELPFILES.

@@@@adding_help_files#Adding help files
You can use macro addhelpfile() to add a file name to HELPFILES.  For
example, addhelpfile("mymacros.hlp") and addhelpfile("mymacros.hlp",T)
add "mymacros.hlp" at the start and end of HELPFILES, respectively.

@@@@file_related_keywords#File related keywords
You can use gethelp() keywords 'file', 'orig', 'alt' and 'key', but in
that case only the current help file is scanned, not the files in
HELPFILES.

@@@@history_note#History note
help() is implemented as a macro which invokes gethelp().

NOTE: Prior to Version 4.12, gethelp() was named help() and there was no
macro named help().

@@@@see_also#Cross references
See gethelp(), getusage() and usage().
@@@@______

====hft()#time series,complex arithmetic
%%%%
hft(hx [,divbyT:T]), hx a REAL matrix considered as complex in Hermitian
  form
%%%%
@@@@usage#Usage
hft(hx) where hx is a REAL vector or matrix, computes the real discrete
Fourier transform of each column of hx, considered as a complex series
with Hermitian symmetry in packed Hermitian form.

Any MISSING values in hx are replaced by 0 in computing the result and a
warning message is printed.

hft(hx,divbyt:T) does the same, except the result is divided by the
number of rows of hx.

@@@@inverse_transform#Inverse transform
hconj(rft(rx,divbyt:T)) is the inverse of hft() in the sense that hx and
hconj(rft(hft(hx),divbyt:T)) are equal except for rounding error.

@@@@limitation_on_length#Limitation on length
The largest prime factor of nrows(hx) must not exceed 29.  You can use
primefactors() to find the maximum factor of nrows(hx) and goodfactors()
to find a length >= nrows(hx) which has no prime factors > 29.  In
addition, the product of all the "unpaired" prime factors can't be too
large.  For example N = 3*5*7*11*13*17*M^2 = 255255*M^2, where M is an
integer, breaks the algorithm and hence is not allowed.

@@@@see_also#Cross references
See also cft(), rft(), hconj(), primefactors(), goodfactors().

See topic 'complex' for discussion of complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====himag()#time series,complex arithmetic
%%%%
himag(hx), hx a REAL matrix representing complex data with Hermitian
  symmetry
%%%%
@@@@usage#Usage
himag(hx) computes the imaginary part of the packed Hermitian matrix hx.
For examplem, himag(vector(1,2,3,4,5)) is vector(0,5,4,-4,-5) and
himag(vector(1,2,3,4,5,6)) is vector(0,6,5,0,-5,-6).

@@@@______
See also hconj(), cconj(), hreal(), creal(), cimag().

See topic 'complex' for discussion of complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====hist()#plotting,descriptive statistics
%%%%
hist(x [, nbars] [,keyword phrases]), REAL vector x, integer nbars >= 2
hist(x, vector(anchor,width) [,keyword phrases]), anchor REAL scalar,
  width > 0 scalar
hist(x, edges [,keyword phrases]), edges REAL vector with increasing
  elements
hist(x .... , keys:structure(keyword phrases))
Keyword phrases are relfreq:T, freq:T, leftendin:T, outsideok:T, draw:T,
  save:T plus most graphics keywords
%%%%
@@@@usage#Usage
hist(x, nbars) draws a histogram of the data in REAL vector x using with
nbars equal width bars which include all data.  The bar edges are not
"neat".  For example, 1,1.5,2,2.5,3.0, ... are "neat", 2.71,3.82, 4.93,
6.04, ... are not "neat".

Bar heights are in the so called "density scale" with height = (M/N)/W,
where M is the number of values in a bar with width W and N is the
number of non-MISSING values in x.  This choice makes the total area of
the bars = 1.

A value x is included in bar i when L[i] < x <= R[i], where L and R are
vectors of the left and right edges of the bars.

@@@@leftendin#Keyword 'leftendin'
hist(x, nbars, leftendin:T) does the same, except a value x is included
in bar i when L[i] <= x < R[i].  'leftendin:T' can be used with any
variant of hist() arguments and any other keywords.

@@@@freq_and_relfreq#keywords 'freq' and 'relfreq'
hist(x, nbars, freq:T) and hist(x, nbars, relfreq:T) do the same except
that bar heights are frequencies (M) or relative frequencies (M/N) with
no adjustment for bar width.  'freq:T' and 'relfreq:T' can be used with
any variant of hist() arguments.
@@@@______

@@@@default_number_of_classes#Default number of classes
hist(x [,keyword phrases]) does the same using floor(log2(N)) + 1 bars.

@@@@anchored_boundaries#Anchored boundaries
hist(x, vector(anchor, width) [,keyword phrases]) does the same, except
the edges of the bars are of the form anchor + j*width, with anchor +
min(j)*width < min(x) and anchor + min(j) > max(x), with the lowest and
highest bar edges chosen to include all the data.

@@@@specified_boundaries#Specified boundaries
hist(x, Edges [,keyword phrases]) draws a histogram with bar boundaries
from REAL vector Edges with length(Edges) > 2 and satisfying Edges[i] <
Edges[i+1].  The number of bars is nbars = length(Edges) - 1.  A warning
message is printed when bar widths are not all equal and 'relfreq:T' or
'freq:T' is an argument.

@@@@outsideok#Outsideok
hist(x, Edges, outsideok:T) does the same, except it is not an error
when some extreme values are outside the bars defined by Edges.  When
values are outside, a warning message is printed.  Without outsideok:T
this is an error.  A value y is outside the bars when y < Edges[1] or y
> Edges[nbars+1].  Without 'leftendin:T', Edges[1] is outside; with
'leftendin:T', Edges[nbars+1] is outside.
@@@@______

All of the usual plotting related keywords, including 'dumb', 'xlab',
'ylab', and 'title', may be used with hist().  See also topics 'graphs',
'graph_keys', 'graph_borders' and 'graph_files'.

@@@@save_and_draw#Keywords 'save' and 'draw'
result <- hist(x ... , save:T [, draw:T] [,graphics keywords]) returns
structure(x:xvals, y:yvals [,graphics keywords], lines:T, yaxis:F) as
value.  REAL vectors xvals and yvals are such that lineplot(xvals,yvals,
yaxis:F [,graphics keywords]) or lineplot(keys:results) draws the
histogram.  Nothing is drawn unless 'draw:T' is also an argument.

@@@@keys#Keyword 'keys'
An alternate way to specify keyword values is to create a structure
keyValues of keyword values and use 'keys:keyValues' as the only keyword
phrase argument.  For example

  Cmd> keyValues <- structure(xlab:"Bone length",relfreq:T,\
        title:"Bone histogram", ylab:"Relative frequency",save:T)

  Cmd> stuff <- hist(bones,vector(0,.25),keys:keyValues)

does the same as
  Cmd> stuff <- hist(bones,vector(0,.25),xlab:"Bone length",relfreq:T,\
        title:"Bone histogram", ylab:"Relative frequency",save:T)

@@@@see_also#Cross references
See also topic panelhist().
@@@@______

====hpolar()#time series,complex arithmetic
%%%%
hpolar(hx [,unwind:F or crit:val]), hx a REAL matrix representing
  complex data with Hermitian symmetry, val a REAL scalar,
  0.5 < val <= 1
%%%%
@@@@usage#Usage
hpolar(hx) computes the polar form of the packed Hermitian matrix hx,
storing it in pseudo packed Hermitian form, with the amplitude or
absolute value as the real part and the phase as imaginary part.  Thus
hreal(hpolar(hx)) and himag(hpolar(hx)) return REAL matrices whose
columns are the amplitudes and phases of the complex series represented
by the columns of hx.

@@@@angle_units#Angle units
The value of the computed phase is in radians, degrees or cycles
depending on the value of option 'angles'.  See subtopic
'options:"angles"'.  By default the phase is "unwound" so as to minimize
discontinuities arising from wrap-around.

@@@@crit_and_unwind_keywords#Keywords 'crit' and 'unwind'
hpolar(hx,crit:Val), where .5 <= Val < 1 changes the criterion
controlling "unwinding".  The default is .75.  See unwind() for details.

hpolar(hx,unwind:F) suppresses the unwinding.

@@@@see_also#Cross references
See also cpolar(), crect(), hrect().

See topic 'complex' for information on complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====hprdh()#time series,complex arithmetic
%%%%
hprdh(hx1 [, hx2]), hx1 and hx2 REAL matrices representing complex data
  with Hermitian symmetry
%%%%
@@@@usage#Usage
hprdh(hx1, hx2) computes the element-wise complex ratios of elements in
the columns of REAL matrices or vectors hx1 and hx2, considered as
complex matrices in packed Hermitian form.  The result is also a complex
matrix in packed Hermitian form.

Any ratio of the form (0 + 0i)/(0 + 0i) is computed to be 0.

If hx1 or hx2 represents a single complex series (has 1 column), that
series is multiplied by all the series in the other arguments.  For
example, if hx1 is m by 1 and hx2 is m by 3, hprdh(hx1,hx2) is
equivalent to hprdh(hconcat(hx1,hx1,hx1),hx2).

hprdh(hx) is equivalent to hprdh(hx,hx).

@@@@see_also#Cross references
See also hprdhj(), cprdc(), cprdcj(), hdivh(), hdivhj(), cdivc(),
cdivcj().

See topic 'complex' for discussion of complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====hprdhj()#time series,complex arithmetic
%%%%
hprdhj(hx1 [, hx2]), hx1 and hx2 REAL matrices representing complex data
  with Hermitian symmetry
%%%%
@@@@usage#Usage
hprdhj(hx1, hx2) computes the element-wise complex product of elements
in the columns of hx1 and hconj(hx2), considered as complex matrices in
packed Hermitian form.  The result is also a complex matrix in packed
Hermitian form.

If hx1 or hx2 represents a single complex series (has 1 column), that
series is multiplied by all the series in the other arguments.  For
example, if hx1 is m by 1 and hx2 is m by 3, hprdhj(hx1,hx2) is
equivalent to hprdhj(hconcat(hx1,hx1,hx1),hx2).

hprdhj(hx) is equivalent to hprdhj(hx,hx) and produces an packed
Hermitian output matrix with the squared moduli of the elements of hx,
considered as complex numbers, in the real part of the result, with
zeros in the imaginary part.

@@@@see_also#Cross references
See also hprdh(), cprdc(), cprdcj(), hdivh(), hdivhj(), cdivc(),

cdivcj(), hconj().
See topic 'complex' for discussion of complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====hreal()#time series,complex arithmetic
%%%%
hreal(hx), hx a REAL matrix representing complex data with Hermitian
  symmetry
%%%%
@@@@usage#Usage
hreal(hx) computes the real part of the packed Hermitian matrix hx.  For
example, hreal(vector(1,2,3,4,5)) returns vector(1,2,3,3,2) and
hreal(vector(1,2,3,4,5,6)) returns vector(1,2,3 4,3,2).

@@@@see_also#Cross references
See also hconj(), cconj(), himag(), creal(), creal().

See topic 'complex' for discussion of complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====hrect()#time series,complex arithmetic
%%%%
hrect(hx), hx a REAL matrix representing complex data with Hermitian
  symmetry
%%%%
@@@@usage#Usage
hrect(hx) is the inverse operation to hpolar().  Matrix hx is assumed to
contain the polar form of a packed Hermitian series, with amplitudes or
absolute values in the real part and phases in the imaginary part.  The
result contains the real and imaginary parts of that series in packed
Hermitian form.  See topic 'complex' for discussion of complex matrices
in MacAnova.

The phases are assumed to be in units of radians, degrees or cycles
depending on the value of option 'angles'.  See subtopic
'options:"angles"'.

@@@@see_also#Cross references
See also cpolar(), crect(), hpolar().

See topic 'complex' for discussion of complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====htoc()#time series,complex arithmetic
%%%%
htoc(hx), hx a REAL matrix representing complex data with Hermitian
  symmetry
%%%%
@@@@usage#Usage
htoc(hx) returns the fully complex equivalent of the matrix hx,
considering its columns as complex series with Hermitian symmetry.  If
hx is m by n, htoc(hx) is m by 2*n, the real and imaginary parts of
column i of hx in columns 2*i-1 and 2*i of the result.

@@@@see_also#Cross references
See also ctoh(), cconj(), hconj(), hreal(), himag(), creal(), cimag().

See topic 'complex' for discussion of complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====hypot()#transformations
%%%%
hypot(x,y), x and y REAL of the same size and shape, or structures with
  matching REAL components
%%%%
@@@@usage#Usage
hypot(x,y) is mathematically equivalent to sqrt(x^2 + y^2) but can
provide answer when either (i) x^2 + y^2 is too big to be represented in
the computer; or (ii) x^2 + y^2 is smaller than the smallest non-zero
value representable in the computer and thus evaluates to 0.  x and y
must be REAL vectors, matrices, or arrays with the same dimensions.

@@@@structure_arguments#Structure arguments
hypot(x,y) is also defined when x and y are structures of the same
shape.  The result is a structure whose i-th component is hypot(xi,yi),
where xi and yi are the i-th components of x and y.

@@@@character_arguments#Character arguments
hypot(x,y) can be used when both x and y are CHARACTER variables with
matching dimensions.  In that case the result is a CHARACTER variable
describing the transformation of the arguments.  For example,
hypot(vector("X1","X2"),vector("Y1","Y2")) returns
vector("hypot(X1,Y1)", "hypot(X2,Y2)").  This feature may be useful in
creating new labels for a transformed variable.

@@@@see_also#Cross references
See also topics atan(), 'transformations', 'structures', 'labels'.
@@@@______

====if#syntax,control
%%%%
if (Logical){cmd;...}
if (Logical){cmd1;...} else {cmd2;...}
if (Logical1){cmd1;...) elseif (Logical2){cmd2;...} [else {cmd3;...}]
%%%%
@@@@usage_of_if#Usage of 'if'
if(Logical){Statement} allows conditional execution of Statement, an
arbitrarily complex statement or compound statement.  Statement will be
executed if and only if Logical has the value True.  Logical should be a
scalar LOGICAL variable or expression.  A simple example would be
  Cmd> if(min(x) > 0){logx <- log(x);;}

@@@@usage_of_if_else#Usage of 'if ... else'
if(Logical){Statement1} else {Statement2} results in Statement1 being
executed when Logical is True, and Statement2 being executed when
Logical is False.  An example would be
  Cmd> if(min(x) > 0){logx <- log(x);;}else{
         error("Illegal non-positive values")}

@@@@usage_of_if_elseif_else#Usage of 'if... elseif... else'
if(Logical1){Statement1} elseif(Logical2){Statement2} else {Statement3}
executes Statement1 when Logical1 is True, executes Statement2 when
Logical1 is False and Logical2 is True, and executes Statement3 when
both Logical1 and Logical2 are False.  An example would be
  Cmd> if(min(x) > 0){logx < -log(x);;}elseif(max(x) < 0){
            logx <- -log(-x);;}else{
            error("Not all positive and not all negative")}

There can be additional elseif(Logical){Statement} constructs before the
concluding 'else{...}', and the concluding 'else{...}' can be omitted.
The first Statement for which the corresponding Logical is True is
executed.

@@@@value#Value
The value of any of these constructs starting with 'if' is the value of
whichever '{Statement}' is actually executed.  If no value is wanted, it
is good practice to terminate each Statement with ';;' so the value will
be NULL, as in the examples above.  If all the Logicals are False and
there is no concluding 'else{...}', the value is NULL.  For example,
if(2 > 3){ ...}elseif(5 < 4){...} has value NULL.  See below for
examples of how you can the fact that a conditional statement has a
value.  See also topic 'NULL'.

@@@@evaluation_of_logicals_tested
Once a Logical has been found to be True, any subsequent Logicals are
not evaluated and are not even checked for syntactical correctness.

@@@@examples#Examples
  Cmd> if(ismatrix(x)){xinv <- solve(x);;}else {error("not matrix");;}
  Cmd> a <- if(x < 3){1} else {2}# a <- 1 if x < 3 and a <- 2 otherwise
  Cmd> b <- if(x > 0){1} elseif(x < 0){-1} else{0} # b is 1, -1, or 0
@@@@______

@@@@syntactic_restriction#Syntactic restriction
Note: Each '{' following 'if(...)', 'elseif(...)' or 'else' must be on
the same line as the preceding 'if', 'elseif' or 'else'; 'elseif' and
'else' must be on the same line as the preceding '}'.  As usual,
however, you can terminate the line with '\', and continue on the next
line as in the following:
  Cmd> if(x<0)\
         {y <- 1;;}\
       else\
         {y <- 2;;}
@@@@______

====inforead()#input,files,character variables
%%%%
inforead(fileName,Name [,quiet:F, echo:T or F, silent:T, notfoundok:T,\
  nofileok:T,badkeyok:T]), fileName and Name CHARACTER scalars; FileName
  can also be CONSOLE or be string:charVal where charVal is a CHARACTER
  scalar or vector.
%%%%
@@@@usage#Usage
inforead(FileName,Name) returns the comments (lines starting with ')')
following the header line of data set or macro Name on file FileName.
They are returned, with the leading ')' stripped off, as a CHARACTER
scalar which can be printed.

The contents of the data set or macro are ignored and there is no
checking as to whether the header line is in correct format.  The header
lines are not echoed unless 'quiet:F' is an argument; see below.

It is an error if the file cannot be read or if the named data set or
macro is not found, but see keywords 'notfoundok' and 'nofileok' below.

Name must be a quoted string or CHARACTER scalar and FileName normally
has a similar form, but see keyword 'string' below.

@@@@empty_file_name#File name ""
In versions with windows, if FileName is the null string "", you will
be able to select the file using a dialog box.

inforead(FileName) does the same for the first data set or macro on the
file, assuming that the first non-empty line is the header line of a
data set or macro.

@@@@file_keyword#Keyword 'file'
inforead(file:FileName [,Name]) is equivalent to inforead(FileName
[,Name]).
@@@@______

See below for the usage inforead(string:charVec [,Name]).

@@@@example#Example
Example:
  Cmd> haldinfo <- inforead("macanova.dat","halddata"); print(haldinfo)

reads the comments describing data set halddata on file macanova.dat
into variable haldinfo and then prints haldinfo.

Commands save() and asciisave() would save haldinfo in a file along with
the rest of your workspace.  When you later use restore() to recover the
workspace, print(haldinfo) displays information about the data without
having to refer to the original data file.

@@@@keywords#Keywords
Keywords 'quiet', 'silent', 'notfoundok', 'nofileok' and 'badkeyok'
modify the behavior of inforead().  'echo' is recognized but ignored.

  Keyword phrase        Meaning
   quiet:T          Header and descriptive comments will not be printed
                    (the default for inforead())
   quiet:F          Header and descriptive comments will be printed
                    in addition being returned as value.
   silent:T         Only error messages will be printed; incompatible
                    with quiet:F or echo:T
   notfoundok:T     Failure to find the macro or data set is not
                    considered an error so NULL is returned and
                    no error message is printed
   nofileok:T       Failure to open the file is not considered an error
                    so NULL is returned and no error message is printed
   badkeyok:T       Unrecognized or duplicate keywords are silently
                    ignored.

Keywords notfoundok and nofileok are designed to be helpful in a macro.
You can check the returned value using isnull() and take special action
if the isnull() returns True.  See isnull().

@@@@string_keyword#Keyword 'string'
inforead(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 for a data
set or a macro.  In particular, info <- inforead(string:CLIPBOARD) would
read the header information of the first variable on a replica of a data
file in the special variable CLIPBOARD.  In windowed versions, this
would be taken from the Clipboard.  See topic 'CLIPBOARD'.

@@@@string_or_file_keywords#Keywords 'string' and 'file'
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, inforead(quiet:T,"mymacro",
file:"myfile.dat") is equivalent to inforead("myfile.dat","mymacro",
quiet:T).

@@@@see_also#Cross references
See topics 'matread_file' and 'macro_files' for information on the
format of files readable by inforead().

See also matread(), macroread(), read(), save(), asciisave().
@@@@______

====interrupt%#general,syntax,control
%%%%
Type help(interrupt) to get information on how to interrupt output or
stop the execution of a command that is running.
%%%%
@@@@description#Description
To stop the execution of a command after it has been initiated by Return
or Enter, press the interrupt key, defined for specific systems as
follows:
   System        Interrupt Key
   ------        -------------
   Carapace      Interrupt on the File menu or the Interrupt button
   DOS           Ctrl+C
   Unix/Linux    Ctrl+C 

You can also press the interrupt key to stop a large amount of output
being written to the screen or window.

In the windowed versions, you may have to wait a few seconds for the
interruption to happen.
@@@@______

====invbeta()#probabilities,random numbers
%%%%
invbeta(P, alpha, beta [,upper:T or lower:F]), P, alpha and beta REAL,
  elements of P between 0 and 1, those of alpha and beta > 0
%%%%
@@@@usage#Usage
invbeta(p,a,b) computes the pth quantile (100*p percent point) of the
beta distribution with parameters a and b.

The elements of p must be between 0 and 1, inclusive, and the elements
of a and b must be positive REAL numbers.

If p, a, and b are not all scalars (single numbers), all non-scalar
arguments must have must have the same size and shape and any scalar
arguments are used to compute all the elements of the result.

invbeta(p,a,b,upper:T) and invbeta(p,a,b,lower:F) compute an upper tail
quantile mathematically equivalent to invbeta(1 - p,a,b), but more
accurate when p is very close to 1.

invbeta() is the inverse of cumbeta().

@@@@generating_beta_random_variables#Generating beta random variables
invbeta(runi(n),a,b) will generate a random sample of size n from a beta
distribution .

@@@@binomial_confidence_interval#Binomial confidence interval
You can use invbeta() to compute an "exact" confidence for a probability
p based on an observed value x_obs of a binomial random variable with n
trials and P(success) = p.

  Cmd> n <- 19; x_obs <- 11; alpha <- .05 # 95% confidence

  Cmd> p_l <- invbeta(alpha/2,x_obs,n - x_obs + 1)

  Cmd> p_u <- invbeta(alpha/2,x_obs + 1,n - x_obs,upper:T)

  Cmd> vector(p_l,p_u) # exact confidence limits
  (1)       0.335     0.79748

  Cmd> vector(cumbin(x_obs,n,p_u),cumbin(x_obs,n,p_l,upper:T)) #check
  (1)       0.025       0.025

@@@@example#Example
  Cmd> invbeta(.975,3,4) # P(x <= .77722) = .975
  (1)      0.77722

  Cmd> invbeta(.025,3,4,upper:T) # P(x >= .77722) = .025
  (1)      0.77722

@@@@see_also#Cross references
See also cumbeta(), cumbin(), runi().
@@@@______

====invchi()#probabilities,random numbers,confidence intervals
%%%%
invchi(P, df [,noncen, epsilon:eps] [,upper:T or lower:F]), P, df and
  noncen REAL, elements of P between 0 and 1, elements df > 0, elements
  of noncen >= 0, eps > 0 small.
%%%%
@@@@usage#Usage
invchi(p,df) computes the pth quantile (100*p percent point, critical
value) of the chi squared distribution with df degrees of freedom.

invchi(p,df,Noncen [, epsilon:eps]) computes the pth quantile of
non-central chi-squared with non-centrality parameter Noncen.  The
accuracy of the inverse is controled by eps which has default value
1e-10.

The elements of p must be between 0 and 1 and the elements of df must be
positive but need not be integers.  If present, the elements of Noncen
must be non-negative.

Any of p, df or Noncen that are not scalars (single numbers) must be the
same size and shape.  Any argument that is a scalar is used to compute
all elements of the result.

invchi(p,df [,Noncen], upper:T) and invchi(p,df [,Noncen], lower:F)
compute an upper tail quantile mathematically equivalent to invchi(1 -
p, df [,Noncen]).  It may be more accurate for p very close to 1.

invchi() is the inverse of cumchi().

@@@@use_in_tests_and_confidence_limits#Use in tests and confidence limits
If alpha is small, invchi(alpha,df,upper:T) or invchi(1-alpha,df) is the
critical value for a chi-squared test of significance level alpha.

If Ssq is the sample variance from a normally distributed random sample
of size n, then (n-1)*Ssq/invchi(vector(1-alpha/2, alpha/2),n-1) is a
1-alpha confidence interval for the population variance.

@@@@generating_chi_squared_random_variables#Generating chi squared random variables
invchi(runi(n),df [,Noncen]) will generate a random sample of size n
from a possibly non-central chi-squared distribution .

@@@@see_also#Cross references
See also cumchi(), runi().
@@@@______

====invdunnett()#probabilities,comparisons
%%%%
invdunnett(P, ngroup, errorDf [,groupSizes][,onesided:T][,epsilon:eps]
  [,upper:T or lower:F]) P REAL with elements between 0 and 1, elements
  of ngroup integers >= 2, elements of errorDf >= 1, elements of
  groupsizes >= 0, eps > 0, default = .00001.
%%%%
@@@@usage#Usage
invdunnett(P, K, Df) computes Pth quantile (probability point, critical
value) of Tmax, where Tmax is the maximum of abs(t21), abs(t31), ...,
abs(tK1), where t21, t31, ..., tK1 are K-1 t-statistics of the form
tI1 = (xbarI-xbar1)/ stderr(xbarI-xbar1), I = 2,...,K.

xbar1, xbar2, ..., xbarK are the means of independent normal random
samples of the same size with identical population means and variances,
and the standard errors are computed using an independent estimate of
error variance with Df degrees of freedom.  When K = 2 the value is the
same as invstu((1+P)/2, Df).  See invstu().

See below for computing quantiles when the sample sizes differ.

P, K and Df must be REAL.  The elements of P must be between 0 and 1.
The elements of K must be integers >= 2, and the elements of Df must be
>= 1, not necessarily integers.

Any of the arguments P, K or Df that are not scalars must all be
vectors, matrices or arrays of the same size and shape; the value has
the same size and shape.

invdunnett(P, K, Df, upper:T) and invdunnett(P, K, Df, lower:F) compute
the upper tail quantile invdunnett(1-P, K, Df).

@@@@onesided_keyword#Keyword 'onesided'
invdunnett(P, K, Df, onesided:T [,upper:T]) computes the quantiles for
Tmax, where Tmax is now the maximum of t21, t31, ..., tK1, not of their
absolute values.  When K = 2 the value is the same as invstu(P,Df
[,upper:T]).

@@@@epsilon_keyword#Keyword 'epsilon'
invdunnett(P, K, Df [, onesided:T], epsilon:eps), where eps is a small
positive number (default .00001) which controls the accuracy to which
the quantile is computed.  Specifically the logit of the probability
corresponding to the computed quantile should be no farther than eps
from the true logit of P (logit(P) = log(P) - log(1-P).  Since
invdunnett() uses the algorithm underlying cumdunnett() configured so as
to compute probabilities to within .00001, eps should not be smaller
than the default.

@@@@use_in_multiple_comparisons#Use in multiple comparisons
invdunnett() is primarily used to compute critical values for a multiple
comparisons procedure due to C. W. Dunnett wherein a control group
(group 1) is compared to K-1 other treatment groups using K-1 t-tests.

See cumdunnett() for computing P values for the Dunnett test.

@@@@examples_1#Example:
  Cmd> invdunnett(.05, 5, 5*8 - 5,upper:T)
computes the two-sided critical value for the Dunnett test with
significance level alpha = 0.05 for a completely randomized design with
5 groups, all with sample size 8.
@@@@______

@@@@unequal_group_sizes#Unequal group sizes
invdunnett(x, K, Df, groupSizes [,onesided:T] [,upper:T]) computes
quantiles for Tmax, with REAL argument groupSizes specifying the sample
sizes.

In the simplest usage, groupSizes is a vector (ndims(groupSizes) = 1),
with elements >= 0.  If groupSizes is a matrix or array
(ndims(groupSizes) > 1), it is treated as if it were a vector, matrix or
array, with one less dimension, each of whose elements is a vector with
length = last dimension of groupSizes.  The first ndims(groupSizes) - 1
dimensions of groupSizes must match the dimensions of any of x, K, or DF
which is not a scalar.  In particular, a m by 1 matrix, which is treated
as a vector of length m by most MacAnova functions, is interpreted by
invdunnett() as a set of m vectors of length 1.

In computing an element of the result based on a vector of group sizes
(either all of groupSizes when it is a vector, or a row or "slice" of
groupSizes when ndims(groupSizes) > 1), invdunnett() uses up to k of the
non-zero leading values in the vector, where k is the corresponding
element of K.  If there are fewer than k non-zero values, the last one
is replicated as many times as needed.  It is an error to have a zero
value followed by a nonzero value or to have all values zero.

If there is only 1 non-zero value in a row or "slice" of groupSize, the
replication of this element means the group sizes are assumed to be
equal.  In particular, this is the interpretation when groupSizes is a
scalar or a m by 1 matrix.

@@@@examples_2#Examples
  Cmd> invdunnett(.05, 4, 12 - 4, vector(6,2,2,2), upper:T)

computes the 5% critical value for a completely randomized design with 4
groups and sample sizes 6, 2, 2 and 2.

  Cmd> invdunnett(.05, vector(3,4), vector(12 - 3, 12 - 4),\
        matrix(vector(6,3,3,0, 6,2,2,2),4)', upper:T)

computes 5% critical values for two completely randomized designs, one
with 3 groups and sample sizes 6, 3, and 3, the other with 4 groups with
sample sizes 6, 2, 2, and 2.  Because trailing values in the rows of
groupSizes are replicated, matrix(vector(6,3, 6,2),2)' would be an
equivalent way to specify the group sizes.

  Cmd> invdunnett(.01, 4, 12 - 4, 3, upper:T)

computes the same result as invdunnett(.01, 4, 12 - 4, upper:T), because
groupSizes is a scalar.

@@@@ratios_of_group_sizes#Ratios of group sizes
Only the ratios of non-zero elements of groupSizes are relevant.  For
example, for 5 groups (K=5), the following groupSizes are equivalent:
vector(5,4,3,3,3), vector(5,4,3), vector(5,4,3,0,0), vector(10,8,6).
vector(5,4,3,0,3) and vector(5,4,3,0,0,1) would be errors because a
non-zero value follows a zero.

@@@@caution
Caution: invdunnett() is very computation intensive.  If you do not have
a fairly fast computer, it may be unacceptably slow.  On one Macintosh
68000 computer with no math coprocessor, a single value took over 2300
seconds to compute.  Until you know how long it will take on your
computer, don't compute more than one value at a time.  Using a somewhat
larger value for epsilon, for example, epsilon:.0001 or epsilon:.0005,
may speed up the calculation at the cost of some loss of accuracy.

@@@@see_also#Cross references
See also cumdunnett(), invstudrng().
@@@@______

====invF()#probabilities,random numbers,confidence intervals
%%%%
invF(P, df1, df2 [,upper:T or lower:F]), P, df1 and df2 REAL, elements
  of P between 0 and 1, those of df1 and df2 > 0
%%%%
@@@@usage#Usage
invF(p,df1,df2) computes the pth quantile (probability point, critical
value) of the F distribution with df1 and df2 degrees of freedom.

The elements of p must be between 0 and 1 and the elements of df1 and
df2 must be positive REAL numbers (not necessarily integers).

If p, df1, and df2 are not all scalars (single numbers), all non-scalar
arguments must have the same size and shape.  Any scalar arguments are
used to compute all elements of the result.

invF(p,df1,df2,upper:T) and invF(p,df1,df2,lower:F) compute the pth
upper tail quantile.  The result is mathematically equivalent to invF(1
- p, df1,df2) but may be more accurate for small p.

invF() is the inverse of cumF().

@@@@use_in_confidence_limits#Use in confidence limits
If S1sq and S2sq are sample variances from independent normal random
samples of sizes n1 and n2,, you can compute a 1 - alpha confidence
interval for the variance Var1/Var2 as
  (S1sq/S2sq)/invF(vector(1-alpha/2, alpha/2), n1-1, n2-1).

@@@@generating_F_random_variables#Generating F random variables
invF(runi(n), df1, df2) will generate a random sample of size n from a F
distribution.

@@@@see_also#Cross references
See also cumF(), runi().
@@@@______

====invgamma()#probabilities,random numbers
%%%%
invgamma(P, alpha [,upper:T or lower:F]), P and alpha REAL, elements of
  P between 0 and 1, those of alpha > 0
%%%%
@@@@usage#Usage
invgamma(p,alpha) computes the pth quantile (100*p percent point) of the
gamma distribution with shape parameter alpha.  Its principal use is to
compute critical values for test statistics with a gamma distribution
but may also be used to compute exact confidence intervals for a Poisson
mean.

The elements of p must be between 0 and 1; the elements of alpha must be
positive but need not be integers.

If neither p nor alpha is a scalar (single number), they must be the
same size and shape.  If just one argument is a scalar, it is used to
compute all the elements of the result.

invgamma(p,alpha,upper:T) and invgamma(p,alpha,lower:F) compute the pth
upper tail quantile.  The result is mathematically equivalent to
invgamma(1 - p, alpha) but may be more accurate for small p.

invgamma() is the inverse of cumgamma().

2*invgamma(p,df/2 [,upper:T]) is equivalent to invchi(p,df [,upper:T]).

@@@@generating_gamma_random_variables#Generating gamma random variables
mu*invgamma(runi(n),alpha)/alpha will generate a random sample of size n
from a gamma distribution with mean mu and shape parameter alpha.

@@@@poisson_confidence_interval#Poisson confidence interval
You can use invgamma() to compute an "exact" confidence interval for mu
based on an observed value x_obs of a Poisson random variable with mean
mu.
  Cmd> x_obs <- 11 # observed value of x

  Cmd> mu_l <- invgamma(.025,x_obs) # lower 95% limit

  Cmd> mu_u <- invgamma(.025,x_obs+1,upper:T) # upper 95% limit

  Cmd> vector(mu_l,mu_u) # "exact" 95% confidence interval for mu
  (1)      5.4912      19.682

  Cmd> vector(cumpoi(x_obs,mu_u),cumpoi(x_obs,mu_l,upper:T)) # check
  (1)       0.025       0.025

@@@@see_also#Cross references
See also cumgamma(), cumchi(), invchi(), cumpoi(), runi().
@@@@______

====invnor()#probabilities,confidence intervals
%%%%
invnor(P [,upper:T or lower:F]), P REAL with elements of P between 0 and
  1, df > 0
%%%%
@@@@usage#Usage
invnor(P) computes the quantiles (probability points, critical values)
of the normal distribution corresponding to each element of P. P must be
a REAL vector or array with elements between 0 and 1.  The result has
the same size and shape as P.

invnor(P,upper:T) and invnor(P,lower:F) compute upper tail quantiles of
the standard normal distribution.  The result is mathematically
equivalent to invnor(1 - P) but may be more accurate for small P.

A critical value for a two-tail Z-test with significance level alpha or
for a 1-alpha confidence interval may be computed as invnor(alpha/2,
upper:T) or invnor(1-alpha/2).

Critical values for a one-tail Z-test with significance level alpha are
computed as invnor(alpha) (lower tail test) and invnor(alpha,upper:T) or
invnor(1-alpha) (upper tail test).

invnor() is the inverse of cumnor() in the sense that invnor(cumnor(z))
should be the same as z within rounding error and cumnor(invnor(P))
should be the same as P within rounding error.

@@@@see_also#Cross references
See also cumnor(), rnorm()
@@@@______

====invstu()#probabilities,random numbers,comparisons,confidence intervals
%%%%
invstu(P, df [,upper:T or lower:F]), P and df REAL, elements of P
  between 0 and 1, those of df > 0
%%%%
@@@@usage#Usage
invstu(P,df) computes the quantiles (probability points, critical
values) of Student's t- distribution with df degrees of freedom
corresponding to each element of P.  P must be a REAL vector or array
with elements between 0 and 1 and df must be a REAL vector or array with
positive but not necessarily integral elements.

If df is a scalar the result has the same size and shape as P and df is
used to compute all the values.

If P is a scalar, the result has the same size and shape as df and
consists of P-th probability points for the different values of df.

If neither P nor df are scalars, they must be the same size and shape
and corresponding elements of P and df are used to compute elements of
the result.

invstu(P,df,upper:T) and invstu(P,df,lower:F) compute upper tail
quantiles.  The result is mathematically equivalent to invstu(1 - P, df)
but may be more accurate for small P.

invstu() is the inverse of cumstu() in the sense that, within rounding
error, invstu(cumstu(x,df),df) should be the same as x and
cumstu(invstu(P,df),df) should be the same as P.

@@@@use_in_tests_and_confidence_intervals#Use in tests and confidence intervals
A critical value for a two-tail t-test on df degrees of freedom with
significance level alpha or for a 1-alpha confidence interval may be
computed as invstu(alpha/2,df, upper:T) or invstu(1-alpha/2,df).

Critical values for a one-tail t-test on df degrees of freedom with
significance level alpha are computed as invstu(alpha,df) (lower tail
test) and invstu(alpha,df,upper:T) or invstu(1-alpha,df) (upper tail
test).

Bonferronized critical values for K simultaneous two-tail t-tests with
significance level alpha or K simultaneous 1 - alpha confidence
intervals are computed as invstu(.5*alpha/K,df, upper:T).

@@@@generating_students_t_random_variables#Generating students t random variables
invstu(runi(n),df) will generate a random sample of size n from a
Student's t-distribution .

@@@@see_also#Cross references
See also cumstu(), runi().
@@@@______

====invstudrng()#probabilities,comparisons,confidence intervals
%%%%
invstudrng(P, ngroup, errorDf [,epsilon:eps] [,upper:T or lower:F]),
  elements of P between 0 and 1, elements of ngroup integers >= 2,
  elements of errorDf >= 1, eps > 0 small
%%%%
@@@@usage#Usage
invstudrng(P, K, Df) computes the quantiles (probability points,
critical values) of the Studentized range based on K normal variates and
an independent estimate of variance with Df degrees of freedom.  All
three arguments must be REAL.  The elements of P must be between 0 and
1. K must consist of integers >= 2, and the elements of Df must be >= 1,
not necessarily integers.

Any of the arguments P, K or Df that are not scalars must be vectors,
matrices or arrays all of the same size and shape.

invstudrng(P,2,Df) should be the same as sqrt(2)*invstu((1+P)/2,Df)
except for computational error.

invstudrng(P, K, Df, upper:T) and invstudrng(P, K, Df, lower:F) compute
upper tail quantiles.  The result is mathematically equivalent to
invstudrng(1 - P, K, Df).

@@@@use_in_multiple_comparisons#Use in multiple comparisons
Many so-called multiple comparison methods are based on these quantiles,
among them the Tukey HSD (Honestly Significant Difference) and the SNK
(Student-Newman-Keuls) methods.  For example, if you have K independent
normal samples of size n, all with the same variance, and Ssq is the
pooled estimate of the variance, you can compute the 5% HSD as

  Cmd> q05 <- invstudrng(.05,K,K*(n-1),upper:T);hsd <- q05*sqrt(Ssq/n)

@@@@use_in_overall_test_of_equality_of_means#Use in overall test of equality of means
In the same situation, you can test the null hypothesis that all means
are equal by the studentized range statistic computed as Q <-
(max(xbars) - min(xbars))/sqrt(Ssq/n).  This is an alternative to the
ANOVA F-statistic.  You can compute the alpha-level critical value for Q
as invstudrng(alpha, K,K*(n-1), upper:T).  Here xbars is a vector
containing the K sample means and Ssq is the pooled estimate of
variance.  See cumstudrng() for computing P values for Q.

@@@@epsilon_keyword#Keyword 'epsilon'
invstudrng(P, K, Df, epsilon:eps [,upper:T]), where eps is a small
positive scalar, does the same computation with accuracy influenced by
eps.  The smaller the value of eps, the more accurate the result should
be, but the longer it will take to compute it.  The default value of eps
is 0.00001.

@@@@see_also#Cross references
See also cumstudrng(), invstu().
@@@@______

====ipf()#glm,categorical data
%%%%
ipf([Model] [, print:F or silent:T, incr:T, pvals:T, maxiter:m,\
  epsilon:eps]), vec a REAL vector, m an integer > 0, eps REAL > 0
%%%%
@@@@usage#Usage
ipf(Model) uses iterative proportional fitting to compute a Poisson
regression (log linear) fit of the model specified in the CHARACTER
variable Model.  The default output is the deviance from the full model.

See topic 'models' for information on specifying Model.

@@@@inc_keyword#Keyword 'inc'
ipf(Model,inc:T) fits the same model except a sequential analysis of
deviance is computed.  The sequential analysis of deviance has a line
for each term in the model giving the term name, degrees of freedom, and
the change of deviance obtained by including the term in the given
order.  Because each of the submodels must be fit iteratively, with a
complicated models or a large data set ipf(Model,inc:T) can take many
times longer to execute than ipf(Model).

@@@@pvals_keyword#Keyword 'pvals'
ipf(Model [,...], pvals:T) prints chi-squared P values with each
deviance.

If option 'pvals' has value True, P values will be printed unless
pvals:F is an argument.

@@@@model_omitted#Model omitted
ipf([,keywords]) or ipf(,inc [,keywords]) fits the last model used by
any of the GLM commands such as regress() or poisson().  See topic
'glm'.

@@@@defaulting_to_poisson#Defaulting to poisson
If there are any non-factors in the model ipf() defaults to poisson().

ipf() also defaults to poisson(), if it does not identify the model as
balanced.  The only forms of balance it recognizes are complete balance
(equal number of cases in every cell) and balanced main effect models
(no interactions and all two-way marginals have equal cell sizes, for
example a Latin square design)

@@@@side_effect_variables_created#Side effect variables created
ipf() sets the side effect variables RESIDUALS, WTDRESIDUALS, SS, DF,
HII, DEPVNAME, TERMNAMES, and STRMODEL.  See topic 'glm'.  All except
HII should be the same as computed by poisson(Model,inc) used.  Since
HII cannot be computed easily, it is set to a constant vector with
values m/n where m = (Model degrees of freedom) and n is the number of
values in the dependent variable vector.  Thus sum(HII) = m as it
should.  Without keyword phrase 'inc:T' (see below), TERMNAMES has value
vector("","", ...,"Overall model","ERROR1"), DF has value vector(0,0,
..., ModelDF,ErrorDF) and SS has value vector(0,0,...,ModelDeviance,
ErrorDeviance).

@@@@maxiter_and_epsilon_keywords#Keywords 'maxiter' and 'epsilon'
ipf(Model,maxiter:m,epsilon:eps), where m is a positive integer and eps
is positive, is the same as ipf(Model) except up to m iterations may
take place (the default is 25) and eps is the convergence criterion
(default 1e-6).  You need not specify either or both.

@@@@print_and_silent_keywords#Keywords 'print' and 'silent'
ipf(Model [,...], print:F) is the same as ipf(Model [,...])  except that
most printing is suppressed and the only result is to set the side
effect variables.

ipf(Model [,...], silent:T) does computations, creating side effect
variables, but prints nothing except actual error messages.

@@@@limitations#Limitations
Keyword phrase 'coefs:F' cannot be used with ipf().

Coefficients may be retrieved by coefs(); standard errors are not
available.  You must use poisson() if you require standard errors.
@@@@______

====isarray()#macros,general,variables
%%%%
isarray(arg1 [,arg2, ...] [,real:T, logic:T, char:T, integer:T,\
  positive:T, negative:T, nonneg:T])
%%%%
@@@@usage#Usage
isarray(arg) returns True if arg is an array of any type, REAL, LOGICAL,
CHARACTER or LONG, and False otherwise.  If arg is undefined, isarray()
returns False.

isarray(arg,real:T) returns True if and only if arg is a REAL array.
Similarly isarray(arg,char:T) and isarray(arg,logic:T) return True
only if arg is a array of the specified type.  You can specify more
than one acceptable type; for example, isarray(arg,real:T,logic:T)
returns True only if arg is a REAL or LOGICAL array.

isarray(arg, integer:T), isarray(arg, positive:T), isarray(arg,
negative:T) and isarray(arg, nonneg:T) are similar, testing that arg is
a REAL array whose value has the specified property.  You can use
'integer:T' with any of 'positive:T', 'negative:T' and 'nonneg:T'.  You
cannot use 'char:T' or 'logic:T' with these keywords.

@@@@multiple_arguments#Multiple arguments
isarray(arg1, arg2, ..., argk [,keywords]) returns a LOGICAL vector,
each element of which is True or False depending on whether or not the
corresponding argument is a array with the properties, if any, specified
by keyword phrases.

@@@@purpose#Purpose
The principal use of isarray() is in checking the arguments of a macro
for appropriateness.  See argvalue() for another way to check for the
properties of macro arguments.

@@@@examples#Examples
Examples:
  Cmd> isarray(vector(x), matrix(x,4), array(x,2,2,2), structure(x))
      has value vector(T,T,T,F) when x has 8 elements.

  In a macro

   if (!isarray($1,real:T,logic:T)){
     error("$1 is not a REAL or LOGICAL")
   }

  ensures argument 1 is REAL or LOGICAL before proceeding.

@@@@see_also#Cross references
See also array(), error(), ischar(), isdefined(), isfactor(),
isfunction(), isgraph(), islogic(), ismacro(), ismatrix(), isname(),
isnumber(), isnull(), isreal(), isscalar(), isstruc(), isvector().
@@@@______

====ischar()#macros,general,variables,character variables
%%%%
ischar(arg1 [, arg2, ...])
%%%%
@@@@usage#Usage
ischar(arg) returns True if arg is a CHARACTER variable or quoted string
and False otherwise.  If arg is undefined, ischar() returns False.

ischar(arg1, arg2, ..., argk) returns a LOGICAL vector, each element of
which is True or False depending on whether or not the corresponding
argument is of type CHARACTER.

The principal use of ischar() is in checking the arguments of a macro
for appropriateness.  See argvalue() for another way to check for the
properties of macro arguments.

@@@@example#Example
Example:
  Cmd> ischar("hello",3,T) # returns vector(T,F,F).

@@@@see_also#Cross references
See also topics 'macros', isarray(), isdefined(), isfactor(),
isfunction(), isgraph(), islogic(), ismacro(), ismatrix(), isname(),
isnull(), isnumber(), isreal(), isscalar(), isstruc(), isvector().
@@@@______

====isdefined()#macros,general,variables
%%%%
isdefined(arg1 [, arg2, ...])
%%%%
@@@@usage#Usage
isdefined(arg) returns True if arg exists in the MacAnova workspace and
False otherwise.  If arg is a built-in function, isdefined() returns
True.

isdefined(arg1, arg2, ..., argk) returns a LOGICAL vector, each element
of which is True or False depending on whether or not the corresponding
argument actually exists.

In a macro, isdefined() is useful for checking errors in a macro.  For
instance, a macro to compute mean square errors might have the line
 if(!isdefined(SS) || !isdefined(DF)){
    error("SS or DF not defined")}
before attempting to use SS or DF.

@@@@see_also#Cross references
See topics 'macros', isarray(), ischar(), isfactor(), isfunction(),
isgraph(), islogic(), ismacro(), ismatrix(), isname(), isnull(),
isnumber(), isreal(), isscalar(), isstruc(), isvector().
@@@@______

====isfactor()#macros,general,glm,variables
%%%%
isfactor(arg1 [, arg2, ...])
%%%%
@@@@usage#Usage
isfactor(arg) returns True if arg is a factor created by factor() and
false otherwise.  If arg is underfined, isfactor() returns False.

isfactor(arg1, arg2, ..., argk) returns a LOGICAL vector, each element
of which is True or False depending on whether or not the corresponding
argument is a factor.

The principal use of isfactor() is in checking the arguments of a macro
for appropriateness.

@@@@see_also#Cross references
See also topics factor(), 'models', 'glm', anova(), isarray(), ischar(),
isdefined(), isfunction(), isgraph(), islogic(), ismacro(), ismatrix(),
isname(), isnumber(), isnull(), isreal(), isscalar(), isstruc(),
isvector().
@@@@______

====isfunction()#macros,general,variables
%%%%
isfunction(arg1 [, arg2, ...])
%%%%
@@@@usage#Usage
isfunction(arg) returns True if arg is a MacAnova function such as
describe(), sum() or regress() and False otherwise.  If arg is
undefined, isfunction() returns False.

isfunction(arg1, arg2, ..., argk) returns a LOGICAL vector, each element
of which is True or False depending on whether or not the corresponding
argument is a MacAnova function.

The principal use of isfunction() is in checking the arguments of a
macro for appropriateness.  See argvalue() for another way to check for
the properties of macro arguments.

@@@@example#Example
Example:
  Cmd> isfunction(PI, cos, boxcox, T) # returns vector(F,T,F,F)

@@@@see_also#Cross references
See also topics isarray(), ischar(), isdefined(), isfactor(), isgraph(),
islogic(), ismacro(), ismatrix(), isname(), isnull(), isnumber(),
isreal(), isscalar(), isstruc(), isvector().
@@@@______

====isgraph()#macros,general,variables
%%%%
isgraph(arg1 [, arg2, ...])
%%%%
@@@@usage#Usage
isgraph(arg) returns True if arg is a GRAPH variable and False
otherwise.  If arg is undefined, isgraph() returns False.

isgraph(arg1, arg2, ..., argk) returns a LOGICAL vector, each element of
which is True or False depending on whether or not the corresponding
argument is a GRAPH variable.

The principal use of isgraph() is in checking the arguments of a macro
for appropriateness.  See argvalue() for another way to check for the
properties of macro arguments.

@@@@see_also#Cross references
See also topics 'graphs', 'macros', isarray(), ischar(), isdefined(),
isfactor(), isfunction(), islogic(), ismacro(), ismatrix(), isname(),
isnumber(), isnull(), isreal(), isscalar(), isstruc(), isvector().
@@@@______

====islocked()#general,variables
%%%%
islocked(arg1 [, arg2, ...])
%%%%
@@@@usage#Usage
islocked(arg) returns True if arg is a locked variable and False
otherwise.  If arg is undefined, islocked() returns False.

islocked(arg1, arg2, ..., argk) returns a LOGICAL vector, each element
of which is True or False depending on whether or not the corresponding
argument is locked.

@@@@see_also#Cross references
See also lockvars(), unlockvars(), 'variables:"locked_variables"'.
@@@@______

====islogic()#macros,general,variables,logical variables
%%%%
islogic(arg1 [, arg2, ...])
%%%%
@@@@usage#Usage
islogic(arg) returns True if arg is a LOGICAL variable and False
otherwise.  If arg is undefined, islogic() returns False.

islogic(arg1, arg2, ..., argk) returns a LOGICAL vector, each element of
which is True or False depending on whether or not the corresponding
argument is of type LOGICAL.

The principal use of islogic() is in checking the arguments of a macro
for appropriateness.  See argvalue() for another way to check for the
properties of macro arguments.

@@@@example#Example
Example:
  Cmd> islogic("hello",3,T) # returns vector(F,F,T).

@@@@see_also#Cross references
See also topics 'logic', 'macros', isarray(), ischar(), isdefined(),
isfactor(), isfunction(), isgraph(), ismacro(), ismatrix(), isname(),
isnumber(), isnull(), isreal(), isscalar(), isstruc(), isvector().
@@@@______

====ismacro()#macros,general,variables
%%%%
ismacro(arg1 [, arg2, ...])
%%%%
@@@@usage#Usage
ismacro(arg) returns True if arg is a macro and False otherwise.  If arg
is undefined, ismacro() returns False.

ismacro(arg1, arg2, ..., argk) returns a LOGICAL vector, each element of
which is True or False depending on whether or not the corresponding
argument is a macro.

The principal use of ismacro() is in checking the arguments of a macro
for appropriateness.  See argvalue() for another way to check for the
properties of macro arguments.

@@@@see_also#Cross references
See also topics 'macros', isarray(), ischar(), isdefined(), isfactor(),
isfunction(), isgraph(), islogic(), ismatrix(), isname(), isnull(),
isnumber(), isreal(), isscalar(), isstruc(), isvector().
@@@@______

====ismatrix()#macros,general,variables
%%%%
ismatrix(arg1 [,arg2, ...] [,real:T, logic:T, char:T, integer:T,\
  positive:T, negative:T, nonneg:T])
%%%%
@@@@usage#Usage
ismatrix(arg) returns True if arg is a matrix of any type, REAL,
LOGICAL, or CHARACTER, and False otherwise.  For arg to be considered a
matrix it is not necessary that ndims(args) be 2, just that no more than
two dimensions have length greater than 1.  In particular, a scalar or a
vector is considered to be a matrix by ismatrix().  If arg is undefined,
ismatrix() returns False.

ismatrix(arg,real:T) returns True if and only if arg is a REAL matrix.
Similarly ismatrix(arg,char:T) and ismatrix(arg,logic:T) return True
only if arg is a matrix of the specified type.  You can specify more
than one acceptable type; for example, ismatrix(arg,real:T,logic:T)
returns True only if arg is a REAL or LOGICAL matrix.

ismatrix(arg, integer:T), ismatrix(arg, positive:T), ismatrix(arg,
negative:T) and ismatrix(arg, nonneg:T) are similar, testing that arg is
a REAL matrix whose value has the specified property.  You can use
'integer:T' with any of 'positive:T', 'negative:T' and 'nonneg:T'.  You
cannot use 'char:T' or 'logic:T' with these keywords.

@@@@multiple_arguments#Multiple arguments
ismatrix(arg1, arg2, ..., argk [,keywords]) returns a LOGICAL matrix,
each element of which is True or False depending on whether or not the
corresponding argument is a matrix with the properties, if any,
specified by keyword phrases.

@@@@purpose#Purpose
The principal use of ismatrix() is in checking the arguments of a macro
for appropriateness.  See also argvalue() for another way to check for
the properties of macro arguments.

@@@@examples#Examples
Examples:
  Cmd> ismatrix(vector(x), matrix(x,4), array(x,4,1,2), array(x,2,2,2))
      has value vector(T,T,T,F) when x has 8 elements.

   if (!ismatrix($1,real:T)){error("$1 is not a REAL matrix")}
     in a macro would check argument 1 is a REAL matrix.

@@@@see_also#Cross references
See also topics 'matrices', error(), isarray(), ischar(), isdefined(),
isfactor(), isfunction(), isgraph(), islogic(), ismacro(), isname(),
isnull(), isnumber(), isreal(), isscalar(), isstruc(), isvector().
@@@@______

====ismissing()#macros,general,missing values,variables,null variables
%%%%
ismissing(x) where x is REAL, LOGICAL or CHARACTER or a structure all of
  whose components are REAL, LOGICAL, or CHARACTER
%%%%
@@@@usage#Usage
ismissing(x) returns a LOGICAL variable (with the same shape as x) which
is True where x is MISSING and False where x is not MISSING.  x must be
a vector, matrix, or array.  If x is a CHARACTER variable, an empty
string ("") is considered to be a missing value.

If x is a NULL variable, ismissing(x) is NULL.  See topic 'NULL'.

It is also acceptable for x to be a structure, whose non-structure
components are vectors, matrices or arrays.  In that case, ismissing()
returns a structure of the same form, each of whose non-structure
components is the result of applying ismissing() to the corresponding
component of x.

ismissing(x) has the same labels as x, if any.

@@@@examples#Examples
Examples:
   ismissing(vector(1, 3, ?, 7)) and ismissing(vector("A","B","","Z"))
     both return vector(F, F, T, F)
   x[vector(ismissing(x))] <- -1 replaces all MISSING values in x by -1.
   sum(vector(ismissing(x))) returns the number of MISSING values in x,
     whether x is a vector, matrix, array, or structure.

@@@@see_also#Cross references
See also anymissing(), sum().
@@@@______

====isname()#macros,general,variables
%%%%
isname(arg1 [, arg2, ... ] [file:T  or  path:T]), arg1, ... CHARACTER
  scalars
%%%%
@@@@usage#Usage
isname(arg) returns T if the value of arg is a legal MacAnova name.
Argument arg must be a CHARACTER scalar or be missing.  See topic
'variables' for information on what is a legal name.

isname(arg1, ..., argk), where the arguments are either CHARACTER
scalars or missing returns a LOGICAL vector of length k with element j
being True if and only if argument k is a CHARACTER scalar whose value
is a legal MacAnova name.

isname(arg1, ..., path:T) does the same except the arguments are
checked as to whether they are appropriate file names or folder
(directory) names on the computer being used.

isname(arg1, ..., file:T), does the same as with 'path:T' except that
False is returned for any argument that can be only a directory, that is
the name ends in a path name separator ('/', or '\' on Windows or DOS, 
or':' on Mac OS 9).

The checking done with 'path:T' and 'file:T' may not exactly match the
formal definition of what is a legal file name.  For instance, on
Unix/Linux, isname("-myfile.txt") is False, although '-myfile' is a
legal Unix/Linux file name, because names starting with '-' can lead to
difficulties.

It is legal for an argument to be missing.  For example, a <- isname()
sets a to F and a <- isname("cos",,"sin") sets a to vector(T,F,T).

The principal use of isname() is in checking the arguments of a macro
for appropriateness.

@@@@examples#Examples
Examples:
 isname("PI") returns True
 isname("123+4") returns False
 isname("x","@y",,"T","too_long_a_name") returns vector(T,T,F,F,F)
 isname("macanova.hlp","macros/",file:T) returns vector(T,F) on
   Unix/Linux, Windows and DOS
 isname("macanova.hlp","macros/",path:T) returns vector(T,T) on
   Unix/Linux, Windows and DOS
 isname("macanova.hlp",":macros:",file:T) returns vector(T,F) on a
   Mac OS 9
 isname("macanova.hlp",":macros:",path:T) returns vector(T,T) on a
   Macintosh

@@@@see_also#Cross references
See also topics 'macros', isarray(), ischar(), isdefined(), isfactor(),
isfunction(), isgraph(), islogic(), ismacro(), ismatrix(), isnull(),
isnumber(), isreal(), isscalar(), isstruc(), isvector(), nameof().
@@@@______

====isnull()#macros,general,variables,null variables
%%%%
isnull(arg1 [, arg2, ...])
%%%%
@@@@usage#Usage
isnull(arg) returns T if arg has type NULL and false otherwise.

isnull(arg1, arg2, ..., argk) returns a LOGICAL vector, each element of
which is True or False depending on whether or not the corresponding
argument is NULL.

See topic 'NULL' for information on NULL variables.

The principal use of isnull() is in checking the arguments of a macro
for appropriateness.

@@@@example#Example
Example:
  Cmd> isnull(NULL, sqrt(2)) # returns vector(T, F)

@@@@see_also#Cross references
See also topics 'macros', isarray(), ischar(), isdefined(), isfactor(),
isfunction(), isgraph(), islogic(), ismacro(), ismatrix(), isname(),
isnumber(), isreal(), isscalar(), isstruc(), isvector().
@@@@______

====isnumber()#macros,general,variables
%%%%
isnumber(arg1 [, arg2, ... ]), arg1, ... CHARACTER scalars
%%%%
@@@@usage#Usage
isnumber(arg) returns T if arg is a CHARACTER scalar or quoted string
such as "-3.1416" which represents a non-MISSING number.  It is an error
if arg is not a CHARACTER scalar.  It returns F when arg does not
represent a non-MISSING number, for example "MacAnova" or "?".  See
topic 'number' for information on what are legal numbers.

isnumber() (with no argument) is legal and returns F.

isnumber(arg1, ..., argk), where the arguments are either CHARACTER
scalars or empty returns a LOGICAL vector of length k with element j
being True if and only if argument k is a CHARACTER scalar which
represents a non-MISSING number.

It is legal for an argument to be missing.  For example, a <- isnumber()
sets a to F and a <- isnumber("3.14",,"henry") sets a to vector(T,F,F).

The principal use of isnumber() is in checking the arguments of a macro
for appropriateness.

@@@@examples#Examples
Examples:

  Cmd> isnumber("3.14")
  (1) T

  Cmd> isnumber(3.14) # not quoted
  ERROR: argument 1 to isnumber() is not CHARACTER scalar

  Cmd> isnumber("1e1000") # too large to be represented
  (1) F

  Cmd> isnumber("3.14",,paste(PI),"PI","?","T","3d10")
  (1) T       F       T       F       F       F       T

@@@@see_also#Cross references
See also topics 'macros', isarray(), ischar(), isdefined(), isfactor(),
isfunction(), isgraph(), islogic(), ismacro(), ismatrix(), isname(),
isnull(), isreal(), isscalar(), isstruc(), isvector(), nameof().
@@@@______

====isreal()#macros,general,variables
%%%%
isreal(arg1 [, arg2, ...] [,positive:T or negative:T or nonneg:T]\
  [,integer:T])
%%%%
@@@@usage#Usage
isreal(arg) returns True if arg is a REAL variable and False otherwise.
If arg is undefined, isreal() returns False.

isreal(arg, integer:T) does the same, except that True is returned only
if arg is REAL and all the values are integers.

isreal(arg, positive:T), isreal(arg, negative:T) and isreal(arg,
nonneg:T) do the same, except that True is returned only if arg is REAL
and all its elements have the indicated properties.  You can use
'integer:T' here as well.

@@@@multiple_arguments#Multiple arguments
isreal(arg1, arg2, ..., argk [keywords]) returns a LOGICAL vector, each
element of which is True or False depending on whether or not the
corresponding argument is REAL and satisfies the properties specified by
any keywords.

@@@@purpose#Purpose
The principal use of isreal() is in checking the arguments of a macro
for appropriateness.  See argvalue() for another way to check for the
properties of macro arguments.

@@@@example#Example
Example:
  Cmd> isreal("hello",3,T)  # returns vector(F,T,F).

@@@@see_also#Cross references
See also topics 'macros', isarray(), ischar(), isdefined(), isfactor(),
isfunction(), isgraph(), islogic(), ismacro(), ismatrix(), isname(),
isnull(), isnumber(), isscalar(), isstruc(), isvector().
@@@@______

====isscalar()#macros,general,variables
%%%%
isscalar(arg1 [,arg2, ...] [,real:T, logic:T, char:T, integer:T,\
  positive:T, negative:T, nonneg:T])
%%%%
@@@@usage#Usage
isscalar(arg) returns True or False, depending on whether arg is a
scalar, that is a REAL, LOGICAL, or CHARACTER variable all of whose
dimensions are 1.  If arg is undefined, isscalar() returns False.

isscalar(arg,real:T) returns True if and only if arg is a REAL scalar.
Similarly isscalar(arg,char:T) and isscalar(arg,logic:T) return True
only if arg is a scalar of the specified type.  You can specify more
than one acceptable type; for example, isscalar(arg,real:T,logic:T)
returns True only if arg is a REAL or LOGICAL scalar.

isscalar(arg, integer:T), isscalar(arg, positive:T), isscalar(arg,
negative:T) and isscalar(arg, nonneg:T) are similar, testing that arg is
a REAL scalar whose value has the specified property.  You can use
'integer:T' with any of 'positive:T', 'negative:T' and 'nonneg:T'.  You
cannot use 'char:T' or 'logic:T' with these keywords.

@@@@multiple_arguments#Multiple arguments
isscalar(arg1, arg2, ..., argk [,keywords]) returns a LOGICAL vector,
each element of which is True or False depending on whether or not the
corresponding argument is a scalar with the properties, if any,
specified by keyword phrases.

@@@@purpose#Purpose
The principal use of isscalar() is in checking the arguments of a macro
for appropriateness.  See argvalue() for another way to check for the
properties of macro arguments.

@@@@examples#Examples
Examples:
  Cmd> isscalar(1,matrix(PI,1), run(5),"hello",F)
has value vector(T,T,F,T,T)

In a macro
  if (!isscalar($1,logic:T)){error("$1 not T or F")}
would check that argument 1 is a LOGICAL scalar.

@@@@see_also#Cross references
See topics 'macros', isarray(), ischar(), isdefined(), isfactor(),
isfunction(), isgraph(), islogic(), ismacro(), ismatrix(), isname(),
isnull(), isnumber(), isreal(), isstruc(), isvector().
@@@@______

====isstruc()#macros,general,structures
%%%%
isstruc(arg1 [, arg2, ... ])
%%%%
@@@@usage#Usage
isstruc(arg) returns True or False, depending on whether arg is a
structure.  If arg is undefined, isstruc() returns False.

isstruc(arg1, arg2, ..., argk) returns a LOGICAL vector, each element of
which is True or False depending on whether or not the corresponding
argument is a structure.

The principal use of isstruc() is in checking the arguments of a macro
for appropriateness.  See argvalue() for another way to check for the
properties of macro arguments.

@@@@see_also#Cross references
See also topics 'structures', 'macros', isarray(), ischar(),
isdefined(), isfactor(), isfunction(), isgraph(), islogic(), ismacro(),
ismatrix(), isname(), isnull(), isnumber(), isreal(), isscalar(),
isvector().
@@@@______

====isvector()#macros,general,variables
%%%%
isvector(arg1 [,arg2, ...] [,real:T, logic:T, char:T, integer:T,\
  positive:T, negative:T, nonneg:T])
%%%%
@@@@usage#Usage
isvector(arg) returns True or False, depending on whether arg is a
vector of any type, REAL, LOGICAL or CHARACTER.  A matrix or array is
considered to be a vector by isvector() if all dimensions except the
first have length 1.  In particular, if arg is a scalar, isvector(arg)
returns True, while if arg is a row vector (dimensions 1,m with m > 1),
isvector(arg) returns False.  If arg is undefined, isvector(arg) returns
False.

isvector(arg,real:T) returns True if and only if arg is a REAL vector.
Similarly isvector(arg,char:T) and isvector(arg,logic:T) return True
only if arg is a vector of the specified type.  You can specify more
than one acceptable type; for example, isvector(arg,real:T,logic:T)
returns True only if arg is a REAL or LOGICAL vector.

isvector(arg, integer:T), isvector(arg, positive:T), isvector(arg,
negative:T) and isvector(arg, nonneg:T) are similar, testing that arg is
a REAL vector whose value has the specified property.  You can use
'integer:T' with any of 'positive:T', 'negative:T' and 'nonneg:T'.  You
cannot use 'char:T' or 'logic:T' with these keywords.

@@@@multiple_arguments#Multiple arguments
isvector(arg1, arg2, ..., argk [,keywords]) returns a LOGICAL vector,
each element of which is True or False depending on whether or not the
corresponding argument is a vector with the properties, if any,
specified by keyword phrases.

@@@@purpose#Purpose
The principal use of isvector() is in checking the arguments of a macro
for appropriateness.  See argvalue() for another way to check for the
properties of macro arguments.

@@@@examples#Examples
Examples:
  Cmd> isvector(7, vector(x), matrix(x,5), array(x,5,1,1), matrix(x,1))
has value vector(T,T,T,T,F) if x has 5 elements.

In a macro
  if(!isvector($1,char:T)){
        error("$1 is not a CHARACTER vector")}
would check that argument 1 is a CHARACTER vector.

@@@@see_also#Cross references
See also topics 'vectors', 'macros', isarray(), ischar(), isdefined(),
isfactor(), isfunction(), isgraph(), islogic(), ismacro(), ismatrix(),
isname(), isnull(), isnumber(), isreal(), isscalar(), isstruc().
@@@@______

====keyvalue()#syntax,macros
%%%%
keyvalue(keyname1:val1, [keyname2:val2, ...] targetkey [, properties]\
  [,default:defVal]), targetkey a CHARACTER scalar, Properties a
  CHARACTER scalar or vector whose elements are one or more of "array",
  "character", "count", "graph", "integer", "logic", "macro", "matrix",
  "nonmissing", "nonnegative", "notnull", "number", "positive", "real",
  "scalar", "square", "string", "structure", "TF" and "vector", and
  defVal arbitrary.
keyvalue(str, targetkey [, properties] [,default:defVal), str a
  structure
keyvalue(, targetkey [, properties] [,default:defVal])
%%%%
@@@@usage#Usage
keyvalue(keyname1:val1, keyname2:val2, ... , TargetKey) attempts to
match keyname1, keyname2, ... with CHARACTER scalar or quoted string
TargetKey.  If no match is found, keyvalue() returns NULL.  If a match
is found, the corresponding keyword value is returned.

keyvalue(keyname1:val1, keyname2:val2, ... , TargetKey, default:defVal)
does the same except that defVal is returned if no matching keyword is
found.

keyvalue(keyname1:val1, keyname2:val2, ..., TargetKey, Properties
[,default:defVal) does the same, except that the value of a matched
keyword is returned only if it has the properties specified by CHARACTER
scalar or vector Properties.  When TargetKey is not matched and
'default:defVal' is an argument, defVal value is returned only if it has
all the properties specified by Properties.  See below for an
explanation of Properties.

The principal use of keyvalue is in a macro when keyname1:val1,
keyname2:val2, ... are supplied by $K as in
  @nsig <- keyvalue($K,"nsig","positive integer scalar", default:5)
See below for another example and topic 'macro_syntax' for an
explanation of $K.

@@@@specifying_keyword#Keyword 'specifying'
TargetKey, the second argument, is usually a legal keyword name such as
"nsig".  In this case an exact match of one of the keyword names is
needed.

However, TargetKey can also contain the "wild card" characters '*' and
'?' so that it provides a pattern used to match a keyword name.  '*'
will match any 0 or more successive characters and '?' will match any
single character.  For example, if TargetKey = "pow*", it matches
keywords 'pow', 'power' and 'powers', among others, but does not match
'polar'.  Similarly, if targetKey = "m??imum", it matches both keywords
'maximum' and 'minimum', among others.  See match() for more information
about inexact matching using '*' and '?'.

You can use structure(keyname1:val1, keyname2:val2, ...) instead of
keyname1:val1, keyname2:val2, ... .

keyvalue(, TargetKey [,Properties]) is legal and returns NULL.
Arguments TargetKey and Properties are checked for appropriateness.

@@@@use_in_macros#Use in macros
The principal use for keyvalue() is in writing macros that expect
keyword phrase arguments.  It allows easy retrieval and checking of
keyword values.  A key point is that it is an error when the value of a
matched keyword value or the default value does not have the specified
property or properties.  When this occurs in a macro, execution of the
macro is terminated.

Here is a fragment of a macro that recognizes an optional macro argument
of the form 'weights:w' where w must be a REAL vector with positive
elements.

  @weights <- keyvalue($K,"weights","real positive vector",\
    default:rep(1,@n))

If 'weights:w' is an argument to the macro, @weights is set to w;
otherwise @weights is set to the default rep(1,@n).  Presumably @n was
set previously.  If w is not a REAL vector with positive elements the
macro will be terminated with the message
  ERROR: value of keyword 'weights' is not a vector of positive REALs

If "weights" were replaced by "weight*", keyvalue() would return w if
'weight:w' or 'weights:w' were an argument.  This is helpful in writing
a more user friendly macro, that recognizes both 'weight' or 'weights'
when 'weights' is expected.

In a macro, keyvalue(structure($K),...) is almost equivalent to
keyvalue($K,...), except that a warning message is printed when there
are no keyword arguments to the macro ($K expands to nothing).

@@@@property_descriptions
                       Description of Properties
Properties is usally a CHARACTER scalar or quoted string containing one
or more of the following, separated by blanks or tabs (not commas):
  "array"     "integer"   "matrix"      "notnull"   "scalar"    "vector"
  "character" "logic"     "nonmissing"  "positive"  "square"
  "graph"     "macro"     "nonnegative" "real"      "structure"

An example would be "nonmissing real vector".  Properties can also be a
CHARACTER vector with each element containing one or more properties
from this list, for example, vector("nonmissing","real","vector").

In addition, there are properties thats are abbreviations for
combinations of properties specifying types of scalars:
  "number" means  "nonmissing real scalar"
  "count"  means  "nonnegative integer scalar"
  "TF"     means  "nonmissing logical scalar"
  "string" means  "character scalar"

Not all combinations of properties are permitted.  See below for
details.

Any 3 character or longer initial segment of a property will match it,
except that "nonnegative", "nonmissing", "string" and "structure"
require 4.  For example, "vec", "vect", "vecto", ... all match "vector".

@@@@property_types#Property types
Each recognized property (other than the abbreviations "TF", "number",
"count and "string") is classified as to whether it describes the type,
shape, value or sign of a variable:
  Kind of property            Property names
     Type           "real", "logic", "character", "macro", "graph",
                    "notnull"
     Shape          "scalar", "vector", "matrix", "array", "structure",
                    "square"
     Value          "integer", "nonmissing"
     Sign           "positive", "nonnegative"

@@@@property_restrictions#Property restrictions
Combinations of properties are restricted as follows:
  No more than one of each of the 4 kinds of property can be specified
    except that "square" and "matrix" can be used together
  Property "structure" is illegal with any Sign or Value property and
    with "macro", "graph" and "notnull"
  Properties "positive", "nonnegative" and "integer" imply properties
    "real" and "nonmissing" and are illegal with any Type property
    except "real". They are legal with property "number"
  Property "nonmissing" is illegal with any Type property except "real"
    and "logical".
  Properties "macro", "graph" and "notnull" cannot be combined with any
    other properties.

@@@@see_also#Cross references
See also argvalue(), getkeywords(), nameof(), isscalar(), isvector(),
ismatrix(), isarray(), isreal(), ischar(), islogic(), ismacro(),
isstruc(), isnumber(), isgraph(), isdefined(), 'keywords', 'macros'.
@@@@______

====keywords#syntax
%%%%
print(nsig:5,x), plot(Obs_No:x,Response:y), regress(Model, pvals:T),
  setoptions(format:"12.5g") are examples of keyword usage
%%%%
@@@@description#Description
Many functions accept 'keyword phrases' such as 'xlab:"Weight"',
'down:T' or 'nsig:7' as optional arguments.

A keyword phrase has the form Name:Value, where Name is a name of no
more than 10 characters starting with a letter (a-z or A-Z).  Value is a
variable or constant.

When used as values of a keyword phrase, 'T' and 'F' can often be
interpreted as 'yes' and 'no' or 'allow' and 'suppress'.

Keywords often provide optional information, or specify variants of the
usual computation. For example, print(nsig:7,x,y,nsig:3,z) prints x and
y with 7 significant digits and z with 3, and screen(Model,mbest:6)
specifies that screen() should find the 6 best subsets of independent
variables.

Keyword phrases may also be used to name components when using
structure() and strconcat(), to label output on most output commands
(print, write, etc.), and to provide labeling information on plotting
commands such as plot() and chplot().  The only limitation is that any
keyword that is specially recognized by the command such as 'labels' or
'format' cannot be used as such a label.

@@@@example#Example
Example:
  Cmd> boxplot(split(wts,race),vertical:T,\
         title:"Weights of Army recruits by race",ylab:"Pounds")

@@@@see_also#Cross references
See also topics 'syntax', structure(), strconcat(), keyvalue()
@@@@______

====kmeans()#multivariate analysis
%%%%
kmeans(y [,means or classes] [,kmax:k1,kmin:k2,start:method,standard:F,
  weights:wts, quiet:T]), y a REAL matrix, means a REAL matrix with
  ncols(y) columns, classes a REAL vector with nrows(y) rows, k1 and k2
  positive integers, k1 >= k2, method one of "random", "optimal",
  "means", or "classes", wts a REAL vector with nrows(wts) = nrows(y)
%%%%
@@@@usage#Usage
kmeans(y, kmax:k1 [, kmin:k2]) performs k-means clusterings of the rows
of REAL matrix y, starting with k1 clusters, and successively merging
clusters until there are k2 clusters.  By default the data are
standardized and the initial clusters are selected randomly.  At each
stage, cases are reallocated among clusters in an attempt to minimize
the sum of the within-cluster sums of squares.  If kmin:k2 is omitted,
k2 is taken to be k1.

It is an error when k2 > k1.

kmeans() returns a structure with components 'classes' and 'criterion'.
Component classes is a nrows(y) by k2-k1+1 matrix (vector if k2 = k1)
containing the cluster membership at each stage.  Component criterion is
a k2-k1+1 REAL vector containing the minimized criterion at each stage.

By default, a brief history of the merging process is printed, including
the values of the criterion being minimized.

@@@@random_optimal_means_and_classes_keywords#Keywords 'random', 'optimal', 'means' and 'classes'
kmeans(y, kmax:k1 [, kmin:k2], start:"random") is identical to kmeans(y,
kmax:k1 [, kmin:k2]).

kmeans(y, kmax:k1 [, kmin:k2], start:"optimal") attempts to select the
initial clusters so as to minimize the within-cluster sums of squares
for column 1 of y.

kmeans(y, Means [, kmin:k2], start:"means"), where Means is a k1 by
ncols(y) matrix, selects as initial cluster j those rows of y that are
closer to row j of Means than to any other row of Means using (Euclidean
distance).  If kmax:k1 is an argument with k1 != nrows(Means), a warning
message is given and nrows(Means) is used.  If there are duplicates
among the rows of Means, a warning message is printed.

kmeans(y, Classes [, kmin:k2], start:"classes"), where Classes is a
vector of nrows(y) positive integers <= 255, uses Classes to specify
initial clusters.  If kmax:k1 is an argument with k1 != max(Classes), a
warning message is given and max(Classes) is used.  If there are empty
classes (not all integers between 1 and max(Classes) are present), the
empty classes are "squeezed out", and max(Classes) reduced accordingly.

@@@@standard_weights_and_quiet_keywords
                          Additional keywords
      standard:F                 Do not standardize before clustering
      weights:wts                Use weighted means and sums of squares
                                 with wts a REAL vector of length
                                 nrows(y) with w[i] > 0.
      quiet:T                    Suppress printing of clustering
                                 history.

@@@@see_also#Cross references
See also cluster().
@@@@______

====labels#general,variables,output
%%%%
This topic has information on coordinate labels.
Functions for working with labels are:
  setlabels(x, labs [,silent:T])
  setlabels(x, NULL) # remove labels
  labs <- getlabels(x [,silent:T])
  labs <- getlabels(x,vector(1,3,5) [,silent:T])
  if (haslabels(x)){..do something with labels...}
  y <- vector(x,labels:labs [, silent:T])
  y <- matrix(x,labels:structure(rowLabs,colLabs) [, silent:T])
  y <- array(x,labels:structure(lab1,lab2,...) [, silent:T])
  y <- structure(comp1, comp2, ..., labels:labs [, silent:T])
  y <- strconcat(var1, var2, ..., labels:labs [, silent:T])
  y <- hconcat(x1,x2,...,labels:structure(rowLabs,colLabs) [, silent:T])
  y <- vconcat(x1,x2,...,labels:structure(rowLabs,colLabs) [, silent:T])
  y <- read(fileName,labels:structure(rowLabs,colLabs))
  y <- matread(fileName,labels:structure(rowLabs,colLabs))
%%%%
@@@@description#Description
MacAnova vectors, matrices and arrays may have labels for each
dimension.  The label for dimension k is a CHARACTER vector with length
dim(x)[k].  When a variable x has any labels it has them for all
dimensions.

A structure Str may have a single vector of labels of length ncomps(Str)
to label the components.  This is distinct from labels the individual
components may have and distinct from the component names.

The primary function of the labels for a variable is to provide
informative identification of coordinates when the variable is printed.

Labels belonging to x are sometimes propagated to new variables computed
from x.  See below for details.

@@@@retrieving_labels#Retrieving labels
getlabels(x) retrieves all the labels, if any, associated with variable
x.  When x is a vector or a structure, the result is a CHARACTER vector;
otherwise the result is a structure with ndims(x) CHARACTER vector
components.

getlabels(x, 2), say, retrieves the labels for dimension 2 of x as a
CHARACTER vector.  getlabels(x,vector(1,3)), for example, retrieves as a
structure with two components the labels associated with dimensions 1
and 3 of x.  See getlabels().

haslabels(x) is True if and only if variable x has coordinate labels.

@@@@removing_labels
                            Removing labels
setlabels(x, NULL), removes the labels from a scalar, vector, matrix,
array or structure x.

@@@@attaching_labels
                            Attaching labels
setlabels(x, Labs) adds coordinate labels to an existing variable.  When
x already has labels they are replaced.

In these usages, Labs is a CHARACTER vector or scalar, or a structure
with CHARACTER vector or scalar components, one for each dimension of
the variable to be labeled.

@@@@examples#Examples
Examples:
  Cmd> setlabels(x, vector("MN","WI","IA","ND","SD","NE")) # x a vector

  Cmd> setlabels(w, structure(vector("M","F"),\
         vector("Urban","Suburban","rural"))) # w a 2 by 3 matrix

It is not an error when the number of vectors of labels supplied does
not match the number of dimensions.  Extra labels are ignored and
missing ones are assumed to be "@" which will be printed as numbers in
parentheses (see below).  In both cases a warning message is normally
printed.

@@@@labels_keyword#Keyword 'labels'
You can use keyword 'labels' on vector(), matrix(), array(), hconcat(),
vconcat(), structure(), strconcat(), read() and matread() to create a
labeled variable.  The general usage
  xxxxxx(... , labels:Labs [,silent:T])
where xxxxxx() is one of these functions and Labs is as described for
setlabels().

@@@@wrong_length_labels#Wrong length labels
Supplying a vector of coordinate labels of the wrong length to
setlabels() is an error.  On other commands on which you can set labels
using keyword 'labels' (matrix(), for example), providing labels of the
wrong length produces only a warning message that the labels will be
ignored.

@@@@silent_keyword#Keyword 'silent'
On any of the commands which set labels, you can suppress warning
messages by keyword phrase 'silent:T'.

@@@@labels_in_files#Labels in files
When variable x has labels, matprint(fileName, x) and matwrite(fileName,
x) write the labels to the file immediately following x in a format that
allows
  Cmd> x <- read(fileName, "x")
to retrieve both data and labels for x from the file.  Topic
'matread_file' describes the file format of labeled variables.  See also
read() and matread().

@@@@expanding_labels#Expanding labels
                        Expanding Scalar Labels
When you provide labels using keyword 'labels' on a command or as an
argument to setlabels(), any scalar labels (quoted strings or CHARACTER
vectors of length 1) are treated specially.

A scalar label, say "root", for a coordinate with length > 1 is expanded
to vector("root1","root2",...).  For example, labels:structure("A","B ")
generates labels vector("A1","A2",...) and vector("B 1","B 2",...).

This doesn't happen if a scalar label starts with '@' or is one of "",
"#", "(", "[", "{", "<", "/", or "\\".

Scalar label "" is expanded to rep("", length) resulting in its
dimension having no visible labels.

Scalar label "#" is expanded to vector("1","2",...).

Scalar label "(" is expanded to vector("(1)","(2)", ...) and similarly
for the other special characters, with the first element of the label
being "[1]", "{1}", "<1>", "/1/", or "\\1\\".

Scalar label "@" is expanded to rep("@", n) and a scalar label starting
with '@', say "@anything" is expanded to rep("@anything", n).  Such
labels are further expanded when they are printed.

@@@@expanding_labels_starting_with_at#Expanding labels starting with '@'
      Expansion of labels starting with '@' when they are printed
A label of the form rep("@", n) or rep("@anything", n) is interpreted
specially when it is printed.  At that time, it is further expanded
similarly to the way scalar labels that do not start with '@' are
expanded when they are created.

rep("@#", n) prints as '1', '2', ... .

rep("@[", n) prints as '[1]', '[2]', ..., and similarly with "@(", "@{",
"@<", "@/",or "@\\".

rep("@", n) prints "bracketed" labels using the default labeling style,
usually using '(' and ')'.  This style can be changed by option
'labelstyle'.  For example, after setoptions(labelstyle:"["), "@" has
the same effect as "@[".  See topic setoptions(), subtopic
'options:"labelstyle"'.

rep("@anythingelse", n) prints as 'anythingelse1', 'anythingelse2', ....

Note: The use of '@' delays the substitution of numerical indices until
they are actually used in printing, so that the same value may have
different printed labels at different times.  See the paragraph on
propagation of labels below.

When successive coordinates have the same type of "bracket" label
starting with '@' created by, say, labels:structure("@[","@[","["), the
printed labels are combined to, say, '[1,2]'.

@@@@examples#Examples
Examples
  Cmd> setlabels(x, structure("#","X"))
  x now has labels vector("1","2",...) and vector("X1","X2",...).

  Cmd> y <- vector(vecread(fileName),labels:structure("Case ","Y"),\
        silent:T)
  y has labels vector("Case 1","Case 2",...) and vector("Y1","Y2",...)

  Cmd> z <- read("MacAnova.dat","irisdata",\
        labels:structure("",vector("Variety","Y1","Y2","Y3","Y3")))
  The first label of z is rep("",nrows(z)) which does not print.

  Cmd> logy <- matrix(log(y),labels:structure("@",log(getlabels(y,2))))
  The labels of logy y will be rep("@",nrows(y)) and vector("log(Y1)",
  "log(Y2)", ...).  When printed the row labels of logy or any subset of
  rows of logy will be '(1)', '(2)', ... .

@@@@label_propagation
                         Propagation of labels
A variable created by extracting part of a labeled variable using
subscripts is labeled with the appropriate subsets of the labels.
Examples:
After
  Cmd> x <- matrix(run(9),3,labels:structure("[","A "))[-1,-1]
x has labels vector("[2]","[3]") and vector("A 2", "A 3").

After
  Cmd> x <- matrix(run(9),3,labels:structure("@[","@A "))[-1,-1]
has labels vector("@[","@[") and vector("@A ","@A ").  When x is
printed, the row labels will be '[1]', '[2]' and the column labels will
be 'A 1', 'A 2', even though these are rows 2 and 3 and columns 2 and 3
of matrix(run(9),3).  That is, the special expansion of labels starting
with '@' occurs when they are printed, not when they are created.

cos(x), sqrt(x), and other transformation of x have the same labels as
x.

ismissing(x), rank(x), rankits(x) and halfnorm(x), but not sort(x) or
grade(x) have the same labels as x.

x' has the same label vectors as x but in reverse order

When the result of sum(x), min(x) and other transformation that operate
along the first dimension of x is not a scalar, its label for the first
dimension is "@" and the remaining labels match those of x.

+x, -x and !x have the same labels as x.

If OP is a binary operator such as '+', '-', '*', '==', ..., but not a
matrix operator such as %*%, %c%, and %C%, then x OP y often has the
labels of x.  When x does not have labels, x OP y may have the labels of
y.  If both x and y are scalar variables, x OP y does not have labels,
even if one or both of x and y do have labels.

When matrices x and y both have labels, x %*% y, x %c% y, and x %C% y
have labels taken from the row and or column labels of x and y in the
obvious way.  When only one of x or y has labels, the result is labelled
as if the one without the labels had row and column labels of the form
rep("@",m).

In most cases, functions and operators that transform structures to
similar shaped structures propagate labels for structure components.
This includes max(), min(), sum(), prod(), sort(), rank(), grade(),
ismissing(), and mathematical transformations such as cos(), log() and
sqrt().

When x is a labelled matrix, eigen(x)$vectors and releigen(x,y)$vectors
have the same row labels as x and column labels of the form
vector("(1)", "(2)", ...).

When x is a labelled matrix, the matrices of left and right singular
vectors as computed by svd() have labels.  Their row vectors are the row
and column labels of x, respectively.  Their column labels are of the
form vector("(1)", "(2)", ...).

If a is a labelled square matrix, the row and column labels of solve(a)
are the column and row labels of a, respectively.

If a is a labelled square matrix, the row and column labels of solve(a,
b) (a %\% b) are the column labels of a and b, respectively; the row and
column labels of rsolve(a,b) (b %/% a) are the row labels of b and a,
respectively.  When b has no labels, they are assumed to have the form
rep("@",m).  See topics solve(), rsolve(), 'matrices'.

When x is a labelled matrix, cor(x) has row and column labels matching
the column labels of x.  cor(x1, x2, ...) has no labels, even if x1, x2,
... have lables.

When x is a labelled matrix, rft(x) and hft(x) have the same column
labels as x with row labels of the form rep("@", nrows(x)).  The same is
true for cft(x) when ncols(x) is even.

If y is a response variable in a GLM command, its labels are propagated
to side effect variables RESIDUALS, WTDRESIDUALS, and HII.

After regress(), COEF and XTXINV are labeled with the names of the
variables (including "CONSTANT" when appropriate).

After any GLM function producing side effect variables DF and SS, DF and
the first dimension of SS are labeled with TERMNAMES.  After manova(),
dimensions 2 and 3 of SS are labeled with the column labels of the
response variable, it if has labels, and with vector("(1)","(2)", ... ),
otherwise.  The actual brackets used in the default labelling are
determined by the value of option 'labelstyle'.  For example, if the
value of 'labelstyle' is "[", the default labels are vector("[1]",
"[2]"',...).  See subtopic 'options:"labelstyle"'.

After manova(), the column labels of the response variable are attached
to the last dimension of each vector, matrix, or array returned by
coefs() and secoefs().

When any term name is longer than 12 characters (the maximum size for a
structure component name), structure output of coefs() and secoefs() is
labeled with the full term names.

When a structure with component labels is printed, the labels are
printed instead of the component names.
@@@@______

====launching#general,files
%%%%
Unix/Linux and DOS: macanova [-q] [File Options] [Screen Options]
                    at Unix/Linux or DOS prompt
Macintosh:          Double click on MacAnova icon or MacAnova file icon
Windows:            Double click on MacAnova for Windows icon
%%%%
@@@@nonwindowed_versions#Nonwindowed versions
For non-windowed versions (Unix/Linux or DOS), type 'macanova' at the
Unix/Linux or DOS prompt.  If the MacAnova directory is not in the
search path, you will need to specify the complete path.  See below for
command line options.

For non-windowed versions, you may also use "redirected" input and
output to run an entire analysis noninteractively and save the output.
   macanova [options] < cmdFile > outputFile
will read commands from cmdFile and save the results in outputFile.

@@@@windows#Microsoft Windows Version
If MacAnova is installed correctly under Windows 95/98/NT/XP there is
a MacAnova entry on the Start menu, with subentries for all installed
versions and possibly for browser based help files.  All versions can
also be launched from the DOS prompt.

In addition, the installer should also register the extentions
.mvbat, .mvsave, and .mvout for MacAnova batch files, save (workspace)
files, and output files.  Double clicking any file with one of those
extensions should start MacAnova, execute the batch file, restore
the save file, and/or open the output file.

Finally, you may drag and drop save, batch, and output files onto the
MacAnova for Windows icon.

See also topic 'dos_windows', 'carapace'.

@@@@gtk#Linux GTK
Assuming the Carapace GTK version has been named macanovacpc and is
in a directory in your search path, type

    macanovacpc [-q] [File Options] [Path Options] [Screen Options] 

at the Unix/Linux prompt, where items in [...] are options.  See below
for details on command line options.  

See also topics 'unix', 'carapace'.

@@@@macintosh#Macintosh Mac OS X
Double click the MacAnova icon.  In addition, the Finder should also
recognize files with extensions .mvbat, .mvsave, and .mvout (files
with creator mat2 and types TeXT, S000, and TeXT) as MacAnova batch
files, save (workspace) files, and output files.  Double clicking
any file of those types should start MacAnova, execute the batch
file, restore the save file, and/or open the output file.  You can,
in fact, shift click on more than one such file and then choose Open
from the Finder File menu to do more than one operation.

It is possible, though rather awkward, to launch MacAnova from
a Terminal window.  Change into the directory where MacAnova is
located; it will show up as MacAnova.app.  Then change into the
MacAnova.app directory, and the Contents directory within that,
and the MacOS directory within that.  There you should find
macanovacpc, which is the actual executable.  Typing ./macanovacpc
will start MacAnova.  In this fashion you may also use command
line options.

See also topic 'macintosh'.

@@@@command_line_options#Command line options
The windowed versions of MacAnova have a greater array of command
line options than the nonwindowed versions.  However, most casual
users will never need these options, particularly for windowed
versions.

The following tables give an option, whether it is usable in
windowed (W) or nonwindowed (N) versions, and its use.  There will
be a 1 in the W or N column if an option can be used exactly once,
and an asterisk if the option can be used multiple times (up to 50).

@@@@fileoptions#File related options
Option              W  N   Use
-restore filename   1  1   execute restore("filename") at startup
-batch filename     *  1   execute batch("filename") at startup
-f startfile        *  1   execute batch("startfile") silently
-help helpfile      1  1   use helpfile as the default help file
-macro filename     *  1   add filename to variable MACROFILES
-open filename      *      open filename in a command window
-data filename      *  1   add filename to DATAFILES
-addhelp filename   *      add filename to HELPFILES
-config filename    1      use filename as the Carapace preference file

@@@@pathoptions#Path related options
Option              W  N   Use
-home pathname      1  1   set variable HOME to pathname
-appdir pathname    1      set MacAnova root directory to pathname
-path pathname      *      add pathname to DATAPATHS
-dpath pathname        1   add pathname to DATAPATHS
-mpath pathname        1   add pathname to DATAPATHS

@@@@otheroptions#Other options
Option              W  N   Use
-q                  1  1   suppress banner at startup
-prompt string      1  1   set the MacAnova prompt to string
-bprompt string     1  1   set the batch prompt to string (for -batch)
-e expression       1  1   execute expression at startup
-eq expression         1   execute expression and then quit
-l lines            1  1   set page height to l lines
-w columns          1  1   set page width to w columns
-hist count         1  1   set history length to count items

@@@@details#Option details

-restore saveFile 
  The equivalent of 'restore("saveFile")' is executed at startup and
  MacAnova.ini.txt is not read and executed.  See 'customize', restore().

-batch batchFile  
  The equivalent of 'batch("batchFile")' is executed after
  initialization.

-f initFile
  File initFile is executed silently as a batch file at startup instead
  of file MacAnova.ini.txt (see 'customize').

-help helpFile 
  Help information will be taken from file helpFile rather than the
  default help file MacAnova.hlp.txt.

-macro macroFile 
  "macroFile" will be added to the beginning of Pre-defined CHARACTER
  variable MACROFILES.  This will mean that pre-defined macro
  getmacros() will search the file before the standard macro files.  You
  can accomplish the same thing after starting MacAnova by
  addmacrofile("macroFile").  See topics getmacros() and addmacrofile().

-open windowFile 
  Load the contents of windowFile into a command-output window, as if
  Open were selected on the File menu.  No startup message printed.

-data dataFile 
  "dataFile" will be added to the beginning of pre-defined CHARACTER
  variable DATAFILES.  DATAFILES is used by pre-defined macro
  getdata() to make it easy to read data from a standard file.  See
  topic getdata().

-addhelp helpFile
  "helpFile" will be added to the beginning of pre-defined CHARACTER
  variable HELPFILES.  Files in HELPFILES are searched when using the
  command help().  See topic help().

-config configFile
  Use configFile instead of the default file MacAnova.config.  Some
  aspects of MacAnova (fonts, window sizes, etc) can be controlled
  through the configuration file.

-home homePath
  Predefined CHARACTER variables HOME will have "homePath" as value
  instead of a default value.  HOME is used to expand file names of the
  form "~/filename".  For instance, when HOME is "dataDir", "~/filename"
  is expanded to "dataDir/fileName".  See topic 'files'.

-appdir appPath
  By default, the last element of DATAPATHS is the directory where
  MacAnova is located.  You may override that value by using -appdir.
  This is really only useful on Unix/Linux, because the location of
  MacAnova cannot be determined at execution time and a default value
  must be used instead.  Here you can override the default.

-path pathName (or -dpath dataPath  or -mpath macroPath)
  Add pathName to the front of the CHARACTER vector DATAPATHS, which
  contains a set of directories that are searched when you attempt to
  read a file (for example, by using vecread(), read(), matread() or 
  macroread()). If the file cannot be found in the default directory,
  MacAnova searches in the directories in DATAPATHS.  See topic
  DATAPATHS.

If -q is present, the startup message will not be printed and the
  welcome screen is not shown.

-e Expr 
  Execute the MacAnova command in Expr as if it were the contents of 
  a batch file.  Expr will be executed before anything else is done.  

-eq Expr 
  Execute the MacAnova command in Expr as if it were the contents of 
  a batch file and then immediately quit.  Expr will be executed
  before anything else is done.  This option does not make sense
  for windowed versions.

-prompt Prompt 
  Sets the non-batch command line prompt.  Usually Prompt should end
  with a space, for example, -prompt "Next? ".  This becomes the default
  prompt that will be set by setoptions(default:T).  See topics
  setoptions(), 'options'.

-bprompt Prompt 
  Sets a prompt to be used with echoed commands in batch files
  specified on the command line (-batch batchFile). Usually Prompt
  should end with a space, for example, -bprompt "HW 1> "..

-l Nlines
  This pre-defines option 'height' to be Nlines, where Nlines is either
  0 or an integer at least 5.  On windowed versions, this only controls
  the height of "dumb" plots. See subtopic 'options:"height"'.

-w Ncols
  This pre-defines option 'width' to be Ncols, where Ncols is an integer
  at least 20.  On windowed versions, this only controls the width of
  "dumb" plots. See subtopic 'options:"width"'.

-hist Nhist
  This pre-defines option 'history' to be Nhist, an integer >= 0.  This
  limits the number of previous command lines that can be saved and
  recalled to Nhist.  The default value is 100.  See subtopic
  'options:"history".

See also topics 'quitting', 'customize'.
@@@@______

====length()#variables,null variables
%%%%
length(x), x a vector, matrix, or array or any other type of variable.
%%%%
@@@@usage#Usage
length(x) computes the total number of elements in the vector, matrix,
or array x.  The value of length(x) is prod(dim(x)).

If x is a NULL variable, length(x) = 0.

If x is a GRAPH variable or a macro, length(x) = 1.

If x is a structure, length(x) is a structure.  If xi is component i of
x, the component i of length(x) has the same component name and value
length(xi).

@@@@see_also#Cross references
See also topics dim(), ndims(), ncomps(), 'NULL', 'graphs'.
@@@@______

====lgamma()#transformations
%%%%
lgamma(x), x REAL or a structure with REAL components
%%%%
@@@@usage#Usage
lgamma(x) returns the natural logarithm of the gamma function of the
elements of x, when x is a REAL scalar, vector, matrix or array.  The
result has the same shape as x.  When x is an integer, lgamma(x) =
log((x-1)!).

If any element of x is MISSING, so is the corresponding element of
lgamma(x).  If any element of x <= 0 or x > 2.5599833278516e305, the
corresonding element of lgamma(x) is MISSING.  In both cases a warning
message is printed.

When x is a structure, all of whose non-structure components are REAL,
lgamma(x) is a structure of the same shape and with the same component
names as x, with each non-structure component transformed by lgamma().

@@@@see_also#Cross references
See topic 'transformations' for more information on lgamma().
@@@@______

====lineplot()#plotting
%%%%
lineplot(x,y [,add:T,linetype:m, impulse:T] [,other graphics keyword
  phrases]), where x is a REAL vector or scalar, y is a REAL vector or
  matrix, and m >= 0 is an integer
lineplot([Graph,] [x,y], keys:str), str a structure whose component
  names are graphics keywords
%%%%
@@@@usage#Usage
lineplot(x,y) makes a connected line plot of the data in vector x and
vector or matrix y, drawing lines between the successive points.  When y
has several columns, each column is graphed separately with different
line types, solid, dashed, ..., repeating cyclically when there are
more columns than distinct line types.

Generally, lineplot() should be used only when the values in x are in
increasing or decreasing order, although there are useful exceptions.

It is not an error when x or y is NULL; a warning message is printed and
no plotting occurs.

@@@@linetype_and_thickness_keywords#Keywords 'linetype' and 'thickness'
lineplot(x,y,linetype:k,thickness:w), k > 0 an integer and w > 0 a REAL
scalar draws lines of type k and width w.  The defaults are k = 1 and w
= 1.  k < 0 is the same as abs(k) and k = 0 is the same as k = -1.  The
interpretation of k and w depend on the computer system on which
MacAnova is running.  See topic 'graph_keys'.

@@@@structure_argument#Structure argument
lineplot(Str), where Str is a structure with at least two REAL
components, is equivalent to lineplot(Str[1], Str[2]).  For example,
lineplot(x,y) and lineplot(structure(x,y)) are equivalent.  Any
components of Str beyond the first two are ignored.

@@@@variable_LASTPLOT#Variable LASTPLOT
lineplot() normally creates or replaces GRAPH variable LASTPLOT which
encapsulates everything in the graph.  In addition, if the graph was
drawn in graphics window I, GRAPHWINDOWS[I] is made identical to
LASTPLOT (I is always 1 in non-windowed DOS and Unix/Linux versions).
You can suppress saving the plot information in LASTPLOT and
GRAPHWINDOWS[I] by including 'keep:F' as an argument.  See topics
'graphs' and 'graph_assign' for information on GRAPH variables and
special variable GRAPHWINDOWS.

@@@@graph_variable_argument#Graph variable argument
lineplot(Graph,x,y) or lineplot(Graph,Str), where Graph is a GRAPH
variable, draws the plot encapsulated in Graph, adding to it new
information.

@@@@add_impulses_lines_and_symbols_keywords#Keywords 'add', 'impulses', 'lines' and 'symbols'
lineplot(x,y,add:T,...) is the same as lineplot(LASTPLOT,x,y,...)
drawing the graph encapsulated in LASTPLOT, adding to it new
information.  An equivalent way to do this is addlines(x,y,...).

When option 'dumbplot' has been set False (see subtopic
'options:"dumbplot"'), the plot will be a low resolution plot unless
'dumb:F' is an argument.

lineplot(x,y,impulses:T) draws vertical lines to the points from the
x-axis (y = 0 line), in addition to drawing connecting lines

lineplot(x,y,lines:F [,...]) is equivalent to plot(x,y [,...]).

lineplot(x,y,symbols:c [,...]) is equivalent to chplot(x,y,symbols:c,
lines:T [,...]).  In particular, when c = "###", points are labeled with
the row number when y is a vector and the column number when ncols(y) >
1.

@@@@short_x_argument#Short x argument
See topic 'graphs' for information on how a scalar or length 2 vector x
specifies equally spaced x-values, on how to save and print plots, and
on writing graphic information to a file.

@@@@graph_keywords#Graph keywords
See topic 'graph_keys' for information on keywords 'title', 'xlab',
'ylab', 'xmin', 'xmax', 'ymin', 'ymax', 'logx', 'logy', 'xaxis',
'yaxis', 'dumb', 'add', 'file', 'linetype', 'thickness', 'silent' and
'notes'.

@@@@keys_keyword#Keyword 'keys'
lineplot([Graph,] keys:structure(x:x,y:y [other keyword phrases)) is
equivalent to lineplot([Graph,] x,y [other keyword phrases]).  See
topic 'graph_keys' for details.

@@@@GRAPHWINDOWS#GRAPHWINDOWS
See topic 'graph_assign' for information on how to plot in graphics
window I by GRAPHWINDOWS[I] <- var, where var is a structure or GRAPH
variables.

@@@@see_also#Cross references
See also topics chplot(), plot(), showplot(), addchars(), addlines(),
addpoints(), tek(), tekx(), vt(), vtx().
@@@@______

====list()#general
%%%%
list([invis:T]) or list(var1 [, var2, ...])
list([all:T, real:T or F, char:T or F, logic:T or F, macro:T or F,\
  struct:T or F, null:T or F, labeled:T or F, notes:T or F,\
  locked:T or F, keep:T, nrows:n1, ncols:n2, ndims:n3]); use F's only
  with all:T, n1, n2, n3 > 0 integers
%%%%
@@@@usage#Usage
list() lists the name, type, and dimensions of all currently active
variables, including structures and macros, but excluding any temporary
or "invisible" variables (variables whose names start with '_').  The
maximum level of any factors is printed.  See factor() and topic
'variables:"invisible"'..

list(invis:T) does the same, but also includes temporary variables and
invisible variables.

list(var1, var2, ..., vark) gives the same information only for the
specified variables.

For a macro, list() also prints 'out-of-line' or 'in-line' depending on
whether or not it has been marked to be expanded out-of-line.  See
topics 'macros', macro().

For any variable, list() may also print any or all of 'labels', 'notes'
or 'locked' depending on whether the variable has dimension lables,
attached notes or is locked.  See topics 'labels', 'notes', 'locks'.

@@@@listing_by_attributes#Listing by attributes
list(size:T [,invis:T]) or list(var1,var2,...,vark,size:T) also lists
the total size of each variable in bytes.  In addition to the memory
required for data in a variable, this total includes a fixed amount (172
bytes in one Linux implementation) for each symbol and each structure
component.  In addition, MacAnova prints the total size of all listed
variables and the total of all memory currently used by MacAnova for
variable and internal storage.

list(varType:T [,invis:T]) where varType is one of 'real', 'factor',
'logic', 'char', 'macro', 'struc', or 'null' specifies that all
variables of the specified types are listed.  More than one keyword
phrase can appear but no variable names.  For example, list(real:T,
logic:T) will list all variables of type REAL or LOGICAL and
list(factor:T) will list all variables that are factors.

list(all:T,varType1:F [,varType2:F...] [,invis:T]) lists all types
except those specified.  For example, list(all:T,macros:F) lists all
objects except macros.

list(notes:T [,invis:T]) limits the listing to variables with notes.
See topic 'notes'.

list(labeled:T [,invis:T]) limits the listing to variables with labels.
See topic 'labels'.

list(locked:T [,invis:T) limits the listing to variables that are
locked.  See topic 'locks'.

list(nrows:r [,...]) lists all REAL, CHARACTER or LOGICAL variables with
first dimension r.

list(ncols:c [,...]) lists all REAL, CHARACTER or LOGICAL with second
dimension c.  When c = 1, vectors are also listed.  'nrows:r' and
'ncols:c' can be used together.

list(ndims:d [,...]) all REAL, CHARACTER or LOGICAL variables with
exactly d dimensions.  For example, list(ndims:1) lists all vectors.

Keywords 'nrows', 'ncols' and 'ndims' can be used together with
'char:T', 'real:T', or 'logic:T' to limit which variables are listed.

Keywords phrases 'labeled:T', 'notes:T' and 'locked:T' can be used
together with type and shape specifying keywords.  They suppress listing
variables that do not meet the additional restrictions.

@@@@wildcard_matching#Wildcard matching
list(Pattern ... [,invis:T]), where Pattern is a quoted string (but not
a CHARACTER variable) which contains one or more of the "wild card"
characters '*' and '?', lists only objects whose names match Pattern.

'*' will match any set of 0 or more consecutive characters of variable
names, and '?' will match any single character.

For example, list("x*") lists all variables whose names start with 'x',
list("*length") lists all variables whose names end in 'length', and
list("c*b???") lists all variables whose names start with 'c' and end
with 'b' followed by any 3 characters, say, "crybaby".  The last does
not match "crybabies", although "c*b???*" would.

list(pat:Pattern ... [,invis:T]) does the same, except Pattern may bea
CHARACTER scalar whose value is a pattern containing wild card
characters, not just a quoted string.
@@@@______

If a variable is "special" the type is preceded by '*'.  Currently the
only special variables are CLIPBOARD, SELECTION (GTK only) and
GRAPHWINDOWS.  See topics 'CLIPBOARD', 'GRAPHWINDOWS' and
'graph_assign'..

@@@@examples_of_wildcard_use#Examples of wildcard use
Examples:
  Cmd> list("*plot") # lists colplot but not plot1 or myplots
  Cmd> list("plot*") # lists plot1 but not colplot or myplots
  Cmd> list("*plot*") # lists all three.

@@@@keep_keyword#Keyword 'keep'
list(...,keep:T [,invis:T]) suppresses the listing, but returns a
CHARACTER vector containing the names of the variables that would
otherwise have been listed; no information on type or dimensions is
returned.

@@@@examples_of_selective_listing#Examples of selective listing
Example:
  Cmd> list("a*", real:T) # or list(pat:"a*", real:T)
will list all REAL variables whose names start with "a".

@@@@see_also#Cross references
See also delete(), listbrief(), dim().
@@@@______

====listbrief()#general
%%%%
listbrief([invis:T]) or listbrief(var1 [, var2, ...])
listbrief([all:T, real:T or F, char:T or F, logic:T or F, macro:T or F,\
  struct:T or F, null:T or F, labeled:T or F, notes:T or F, \
  locked:T or F keep:T, nrows:n1, ncols:n2, ndims:n3]); use F's only
  with all:T, n1, n2, n3 > 0 integers
%%%%
@@@@usage#Usage
listbrief() lists the names of currently active variables, including
structures and macros.  No information on type or dimension is given.

listbrief(invis:T) does the same, but also includes temporary variables
and variables whose names start with '_'.

listbrief(var1, var2, ..., vark) does the same for specified variables,
except that undefined variables in the list are identified.

listbrief(pat:Pattern [,invis:T]) lists variables whose names match the
value of quoted string or CHARACTER variable Pattern.  If Pattern is a
quoted string, 'pat:' may be ommitted.  See list() for details.

You can also use keywords 'real', 'factor', 'logic', 'char', 'macro',
'struc', 'null', 'labeled', 'notes', 'locked', 'all', 'keep', 'nrows',
'ncols', and 'ndims' as in list().

@@@@see_also#Cross references
See also delete().
@@@@______

====loadUser()#general,control,files
%%%%
loadUser(fileName [,reload:T or clear:T]), CHARACTER scalar fileName.
%%%%
@@@@information#Information
Help on loadUser() is in file userfun.hlp.  You can retrieve the help by

  Cmd> userfunhelp(loadUser)

It provides a complete description of loadUser() which you must call
prior to using an externally compiled user function.

@@@@see_also#Cross references
See also topics User() and 'user_fun' in file userfun.hlp.  Type
userfunhelp(User) or userfunhelp(user_fun).  Type userfunhelp() for a
complete list of topics related to user functions.
@@@@______

====locks%#general,variables
%%%%
lockvars(a [,b,c,...] [,silent:T])
unlockvars(a [,b,c, ...] [,silent:T])
islocked(a [,b,c,...])
Typed help(locks) for information on locked variables.
%%%%
@@@@description#Description
A locked variable is a variable that is protected from casual
destruction or modification.  You lock variables using lockvars() and
unlock them using unlockvars().  A few pre-defined variables and macros
such as PI, E, VERSION and redo() are automatically locked at start up.
Most other pre-defined constants and macros are not locked.

It is an error to attempt to assign a value to a locked variable or to a
subscript of a locked variable.

  Cmd> PI <- sqrt(2)
  ERROR: illegal assignment to locked variable near PI <-

  Cmd> a <- run(10); lockvars(a); a[3] <- PI
  ERROR: illegal to assign to subscript of a locked variable near
  a <- run(10); lockvars(a); a[3] <-

If you try to delete a locked variable, it is not deleted and a warning
message (suppressed by 'silent:T') is printed.

  Cmd> delete(a) # delete(a, silent:T) prints nothing
  WARNING: attempt to delete locked variable a

You can force deletion by keyword phrase 'lockedok:T' on delete.

  Cmd> delete(a,lockedok:T); print(a)
  ERROR: argument 1 (a) to print() is not defined

You can unlock a variable using unlockvars().

  Cmd> unlockvars(PI); delete(PI); print(PI)
  ERROR: argument 1 (PI) to print() is not defined

@@@@testing_locked_variable#Testing locked variable
You can test whether variables are locked using islocked().

  Cmd> islocked(E, VERSION, MACROFILES, boxcox, redo)
  (1) T       T       F       F       T

@@@@locked_variable_in_file#Locked variable in file
When the header line on a data set or macro in a file readable by
read(), matread() or macroread() contains the work LOCKED, the value
returned by read(), matread() or macroread() is saved as a locked
variable.
  Cmd> doit <- macroread("macrofile.txt","doit")
  doit  MACRO LOCKED

  Cmd> list(doit)
  doit            MACRO  (in-line) (locked)

@@@@unlockable_variables#Unlockable variables
You cannot lock temporary variables (names starting with '@'), special
variables such as CLIPBOARD and GRAPHWINDOWS and a few other variables
such as LASTPLOT and LASTLINE.

  Cmd> lockvars(LASTLINE)
  ERROR: can't lock variable LASTLINE

@@@@glm_side_effect_variables#GLM side effect variables
If you lock a GLM side effect variable such as RESIDUALS or STRMODEL, it
effectively blocks any more GLM commands such as regress(), anova() or
poisson() until the variable is unlocked or deleted.

@@@@saving_and_restoring#Saving and restoring
save() and asciisave() save the locked/unlocked status of a variable, so
when the workspace file is restored, a locked variable is restored as a
locked variable.

restore(workspaceFile, delete:F) will not restore variables with the
same name as existing locked variables.  Unless the locked variable is a
REAL scalar and the value in the file is the same as the current value,
a warning message is printed.

@@@@see_also#Cross references
See also 'variables', unlockvars(), lockvars(), islocked().

====lockvars()#general,variables
%%%%
lockvars(a [,b,c,...] [,silent:T]), a, b, c, ... arbitrary variables
  other than GRAPHWINDOWS, CLIPBOARD, and SELECTION
%%%%
@@@@usage#Usage
lockvars(var1, var2, ...) marks variables var1, var2, ... as locked
variables.  This means they cannot be deleted or assigned to.  Any named
variables can be locked except for temporary variables (names beginning
with '@') and the "special" variables GRAPHWINDOWS, CLIPBOARD,
SELECTION.  A warning is printed if any argument is a built in function
name or is alreadly locked.  It is an error if any argument is an
expression or a function result.

lockvars(var1, var2, ..., silent:T) does the same except that no warning
message is printed.

When you save a locked variable (see save() and asciisave()), its locked
status is also saved so that when it is restored (see restore()), it
will still be locked.

Locking a variable does not protect it from destruction by restore().

@@@@see_also#Cross references
See also unlockvars(), delete(), 'variables'
@@@@______

====log()#transformations
%%%%
log(x), x REAL or a structure with REAL components
%%%%
@@@@usage#Usage
log(x) returns the natural logarithm (base e log) of the elements of x,
when x is a REAL scalar, vector, matrix or array.  The result has the
same shape as x.

If any element of x is MISSING, so is the corresponding element of
log(x).  If any element of x <= 0, the corresonding element of log(x)
is MISSING.  In both cases a warning message is printed.

When x is a structure, all of whose non-structure components are REAL,
log(x) is a structure of the same shape and with the same component
names as x, with each non-structure component transformed by log().

@@@@see_also#Cross references
See topic 'transformations' for more information on log().
@@@@______

====log10()#transformations
%%%%
log10(x), x REAL or a structure with REAL components
%%%%
@@@@usage#Usage
log10(x) returns the common logarithm (base 10 log) of the elements of
x, when x is a REAL scalar, vector, matrix or array.  The result has the
same shape as x.

If any element of x is MISSING, so is the corresponding element of
log10(x).  If any element of x <= 0, the corresonding element of
log10(x) is MISSING.  In both cases a warning message is printed.

When x is a structure, all of whose non-structure components are REAL,
log10(x) is a structure of the same shape and with the same component
names as x, with each non-structure component transformed by log10().

@@@@see_also#Cross references
See topic 'transformations' for more information on log10().
@@@@______

====log2()#transformations
%%%%
log2(x), x REAL or a structure with REAL components
%%%%
@@@@usage#Usage
log2(x) returns base 2 log logarithm of the elements of x, when x is a
REAL scalar, vector, matrix or array.  The result has the same shape as
x.

If any element of x is MISSING, so is the corresponding element of
log2(x).  If any element of x <= 0, the corresonding element of
log2(x) is MISSING.  In both cases a warning message is printed.

When x is a structure, all of whose non-structure components are REAL,
log2(x) is a structure of the same shape and with the same component
names as x, with each non-structure component transformed by log2().

@@@@see_also#Cross references
See topic 'transformations' for more information on log2().
@@@@______

====logic#variables,syntax,logical variables,missing values,operations
%%%%
a && b, a || b, !a, where a and b are LOGICAL or structures with LOGICAL
  components
LOGICAL constants are T (True) and F (False)
%%%%
@@@@description_of_logical_variables#Description of LOGICAL variables
Elements of a LOGICAL variable have only three possible values -- True,
False, and MISSING.  A LOGICAL variable may be a vector, matrix, or
array.

Logical values are printed as 'T' (True) and 'F' (False), the same
symbols as you use to enter them.  For example, 'a <- vector(T,F,F,T)'
creates a LOGICAL vector of length 4.

When used as the value of a keyword phrase, as in 'quiet:T', T and F can
usually be interpreted as 'yes' and 'no', respectively.

You can also create LOGICAL data as the result of comparing REAL,
LOGICAL or CHARACTER variables using the following comparison operators:

@@@@comparison_operators_list#Comparison operators list
There are 6 comparison operators used with REAL, LOGICAL and CHARACTER
data and structures of such data.
 Comparison
  Operator  Precedence  Meaning
    a == b      8       Equal or same
    a != b      8       Not equal or different
    a < b       8       Less than
    a <= b      8       Less than or equal
    a > b       8       Greater than
    a >= b      8       Greater than or equal

@@@@logical_operators_list#Logical operators list
There are three purely operators used only with LOGICAL data.
   Logical
  Operator  Precedence  Meaning
   a || b       5       Logical Or (T||T,T||F,F||T are True, F||F False)
   a && b       6       Logical And (T&&T is True, T&&F,F&&T,F&&F False)
     !a         7       Logical Not (!T is False, !F is True)

@@@@precedence#Precedence
The precedence level in the lists of operators above affects the order
of evaluation when there is more than one operator in an expression.  An
operator with higher precedence is evaluated before one with lower
precedence.  For example, MacAnova interprets T && F || T && T as
(T && F) || (T && T) because '&&' has higher precedence (6) than '||'
(5).

See topic 'precedence' for a complete discussion of operator association
and precedence.

@@@@comparison_operators
                          Comparison Operators
Comparison operators are most useful with REAL and CHARACTER data.  When
they are used with LOGICAL data, True and False are interpreted as 1 and
0, respectively, in the same way as with arithmetic operators +, -, *,
and ^ or ** (see 'arithmetic').  In particular F == F and T == T are
True and F == T and T < F are False.

Comparison operators do not "associate".  For example, an expression
like '3 < x <= 5' is meaningless and is an error.  Instead, you can use
'3 < x && x <= 5'.

As you would expect, the precedence of comparison operators is lower
than all arithmetic operations (see 'arithmetic') so that, for example,
3*4 == 14-2 is interpreted as (3*4) == (14-2) and is True.

@@@@comparison_of_character_data#Comparison of CHARACTER data
CHARACTER variables are compared using the ASCII collating sequence.
Most punctuation and all numerals are "less than" upper case letters
which in turn are "less than" lower case letters.  A space is "less
than" all printable characters.  Here is the explicit ordering starting
with space:
    !"#$%&'()*+,-./0123456789:;<=>?
   @ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_
   `abcdefghijklmnopqrstuvwxyz{|}~
On computers with extended character sets, the ordering is dependent on
the internal representation of the characters.

@@@@comparisons_with_MISSING#Comparisons with MISSING
Here's what happens when you make a comparison involving a MISSING
value.
 Operators '<', '<=', '>', or '>=':  The result is MISSING.
 Operator '==' : Result is True only when if both operands are MISSING
 Operator '!=' : Result is True only when just one operand is MISSING.

@@@@examples#Examples
Examples:
   2 == 1, 3 != 3, 3 < 1, T == F, and T > 1 all have the value False
   2 == 2, 3 != 2, 3 > -1, F == F, and 0 == F all have value True
   "A" > "a", "A" != "A", and "MacAnova 2" == "MacAnova 3" are all False

@@@@special_characters#Special characters
Because '<-' is the assignment operator, 'a<-5' will always be
interpreted as "assign 5 to a" even if what is wanted is a comparison of
a with -5.  To obtain the latter a space must follow '<' as in 'a < -5'.

On Mac OS 9, you can use 'Option+<', 'Option+>' and 'Option+=' in
place of '<=', '>=', and '!=', respectively.

@@@@logical_operators
                        Purely logical operators
You can use operators '&&', '||' and '!' (logical AND, OR and NOT) to
combine several conditions to make a single condition or to specify the
opposite of a condition.  For example, (x > 1) && (x < 3) is True if and
only if the value of x is greater than 1 and less than 4 and (x < 0) ||
(y < 0) is True if and only if one or both of x and y is negative.
Also, !(x < 0) means the same as x >= 0.

If an operand of '||', '&&' or '!' is MISSING, so is the result .

The precedence of logical operators is lower than the precedence of
arithmetic expressions (see 'arithmetic') and comparison operations.
For example, 'x > 1 && x < 4' is interpreted as '(x > 1) && (x < 4)',
and is True if and only if the value of x is greater than 1 and less
than 4.  Because the precedence of '!' is lower than the precedence of
the comparison operators, expressions like '! a < b' are evaluated as
'!(a < b)'.  See also topic 'precedence'.

Examples:
   F && T, F || F, and !T all have the value False
   F || T and !F have the value True

@@@@alltrue_and_anytrue
                   Functions alltrue() and anytrue()
In contrast with the C programming language, both expressions that are
combined with '&&' and '||' are always evaluated regardless of the value
of the first expression.  For example, in
   (sqrt(2) < sqrt(3)) || (log(5) < log(6))
both log(5) and log(6) are evaluated although the final value of the
expression (True) could have been determined once it was found that
sqrt(2) < sqrt(3) was True.

alltrue() and anytrue() provide the C behavior.  For example
  Cmd> anytrue(sqrt(2) < sqrt(3), log(5) > log(6)) # value is True

and

  Cmd> alltrue(sqrt(4) < sqrt(2), log(5) < log(6)) # value is False

evaluate only the first arguments.

@@@@nonscalar_operands
           Comparison and logical operations with non-scalars
MacAnova allows comparison of or logical combination of arrays of
different sizes entirely analogously to the way they can be combined
arithmetically by '+', '-', '*', '/', '^', and '%%'.  For instance, '2 <
run(3)' is vector(F,F,T).  See topic 'arithmetic' for details.

When one of the operands is a structure, each of its components is
combined with the other argument, producing a structure with the same
shape as the structure argument.  If both arguments are structures, they
must have the same shape and the corresponding components are combined.
In either case, all the components of a structure must have the same
type and all components must be compatible.  See topic 'structures'.
@@@@______

====logistic()#glm,regression,categorical data
%%%%
logistic([Model],n:Denom [, incr:T, offsets:vec, print:F or silent:T,\
  pvals:T, maxiter:m, epsilon:eps, coefs:F, problimit:smallVal]), Denom
  REAL scalar or vector > 0, vec a REAL vector, m an integer > 0, eps
  and smallVal small REAL scalars > 0.
%%%%
@@@@usage#Usage
logistic(Model,n:Denom) computes a logistic regression fit of the model
specified in the CHARACTER variable Model.  If y is the response
variable in the model it must consist of integers y[i] >= 0.  Denom must
either be an integer scalar >= max(y) or a REAL vector of the same
length as y with Denom[i] >= y[i].  Estimation is by maximum likelihood
on the assumption that y[i] is binomial with Denom[i] trials (Denom
trials for scalar DENOM).

If either Denom or y contains non-integer values a warning message is
printed.

See topic 'models' for information on specifying Model.

@@@@side_effect_variables_created#Side effect variables created
logistic() sets the side effect variables RESIDUALS, WTDRESIDUALS, SS,
DF, HII, DEPVNAME, TERMNAMES, and STRMODEL.  See topic 'glm'.  Without
keyword phrase 'inc:T' (see below), TERMNAMES has value vector("","",
...,"Overall model","ERROR1"), DF has value vector(0,0,...,ModelDF,
ErrorDF) and SS has value vector(0,0,...,ModelDeviance,ErrorDeviance).

@@@@output#Output
If, say, Model is "y=x1+x2", an iterative algorithm is used to predict
logit(E[y/Denom]) as a linear function of x1 and x2, where logit(p) =
log(p/(1-p)).  A two line Analysis of Deviance table is printed.

Line 1 is the difference 2*L(1) - 2*L(0), where L(0) is the log
likelihood for a model with all coefficients 0 and L(1) is the maximized
log likelihood for the model fit.

Line 2 is 2*L(2) - 2*L(1) where L(2) is the maximized log likelihood
under a model fitting one parameter for every y[i].  Under certain
conditions, the latter can be used to test the goodness of fit of the
model using a chi-squared test.

@@@@incremental_deviances#Incremental deviances
logistic(Model,n:Denom,inc:T) computes the full logistic model and all
partial models -- only a constant term, the constant and the first term,
and so on.  It prints an Analysis of Deviance table, with one line for
each term, representing a difference 2*L(i) - 2*L(i-1) where L(i) is the
maximumized log likely for a model including terms 1 through i, plus the
deviance of the complete model labeled as "ERROR1".  Each line except
the last can be used in a chi-squared test to test the significance of
the term on the assumption that the true model includes no later terms.

@@@@omitting_model#Omitting model
If you omit Model (logistic(,n:Denom ...)), the model from the most
recent GLM command such as poisson() or anova(), or the model in
CHARACTER variable STRMODEL is used.
@@@@______

Computations are carried out using iteratively reweighted least squares.

logistic(Model,n:Denom,...) is equivalent to glmfit(Model,n:Denom,
dist:"binomial", link:"logit",...).

@@@@problimit_warning#Problimit warning
If you get a warning message similar to the following
   WARNING: problimit = 1e-08 was hit by logistic() at least once
it usually indicates either the presence of an extreme outlier or a best
fitting model in which many of the probabilities are almost exactly 0 or
1.  The latter case may not represent any problem, since the fitted
probabilities at these points will be 1e-8 or 1 - e-8.  You can try
reducing the threshold using keyword 'problimit' (see below), but you
will probably just get the message again.
@@@@______

                     Other keyword phrases
Keyword phrase  Default  Meaning
@@@@maxiter_keyword#Keyword 'maxiter'
  maxiter:m       50     Positive integer m is the maximum number of
                         iterations that will be allowed in fitting

@@@@epsilon_keyword#Keyword 'epsilon'
  epsilon:eps    1e-6    Small positive REAL specifying relative error
                         in objective function (2*log likelihood)
                         required to end iteration

@@@@problimit_keyword#Keyword 'problimit'
  problimit:small 1e-8   Iteration is restricted so that no fitted
                         probabilities are < small or > 1 - small. Value
                         of small must be between 1e-15 and 0.0001.

@@@@offsets_keyword#Keyword 'offsets'
  offsets:OffVec none    Causes model to be fit to logit(p) to be
                         1*Offvec+Model, where OffVec is a REAL vector
                         the same length as response y.  Note OffVec is
                         in logit units.  See topic 'glm_keys' for more
                         details.

@@@@pvals_keyword#Keyword 'pvals'
  pvals:T or F      F    Nominal chi-squared P-values will be printed
                         for each deviance.  The default value can be
                         changed by setoptions(pvals:T).  See topics
                         setoptions(), 'options'.

@@@@print_silent_and_coefs_keywords#Keywords 'print', 'silent' and 'coefs'
See topic 'glm_keys' for information on keyword phrases print:F,
silent:T, coefs:F

@@@@examples_of_offset_use#Examples of the use of 'offsets'

  Cmd> logistic("y=x", n:15, offsets:3*x, inc:T, pvals:T)
The P value associated with x can be used to test the hypothesis H0:
beta1 = 3 in the model log(p/(1-p)) = beta0 + beta1*x.

  Cmd> logistic("y=1", n:20, offsets:rep(log(.25/(1-.25)),length(y)),\
       inc:T, pvals:T)
The P value associated with the CONSTANT term can be used to test H0: p
= .25, assuming y contains a random sample from a binomial distribution
with n = 20.
@@@@______

====lowess()#regression,descriptive statistics,plotting
%%%%
result <- lowess(x, y [,xpred:xp] [,fract:f] [,iter:m] [, delta:Delta])
  REAL nonMISSING vectors x, y, xp, nondecreasing x, xp, length(x)=
  length(y), REAL scalars f and Delta, 0 < f <= 1, Delta >= 0, integer
  iter > 0; result is structure(x:x,y:yfit [,xpred:xp,ypred:yp])
%%%%
@@@@introduction#Introduction
lowess() uses the LOWESS smoother algorithm to summarize the dependence
of a REAL vector y on a non-decreasing REAL vector x of the same length.

The assumed model is y = g(x) + e, where g(x) is a "smooth" unknown
function of a predictor x and e is an random "error" with E[e] = 0.  The
smoothed output values are estimates of g(x).

Optionally lowess() also estimates E(yp|xp) = g(xp), where xp may differ
from all x[i], assuming approximately linear dependence near xp.

LOWESS is a resistant (to outliers) locally linear smoother.  See below
for more information.

@@@@usage#Usage
Result <- lowess(x,y) and Result <- lowess(structure(x,y)) use the
LOWESS smoother to find a vector ys with ys[i] = smoothed y value
corresponding to x[i].  x and y must be REAL vectors with the same
length and with no MISSING elements.  Also, x must be non-decreasing,
that is x[i] <= x[i+1].

Result = structure(x:x, y:ys), where x is identical to the input x
vector and ys is a REAL vector the same length as x and y.

Result <- lowess(x,y, xpred:xp) and Result <- lowess(structure(x,y),
xpred:xp) do the same but also compute a vector yp of fitted values
corresponding to REAL vector xp using weighted least squares.  xp must
have no MISSING values and must be nondecreasing.

With xpred:xp, Result = structure(x:x, y:y, xpred:xp, ypred:yp), where
yp is a REAL vector the same length as xp with yp[i] the predicted value
corresponding to xp[i].  When xp[i] = x[j], yp[i] = ys[j].  If xp[i] <
x[1] or xp[i] > x[n], where n = length(x), yp[i] is computed by
extrapolation using the straight line used to compute ys[1] or ys[n].

When there are tied x[i]'s, say x[i] = x[i+1] = ... x[i+k-1], ys[i] =
ys[i+1] = ... = ys[i+k-1].

You can modify the behavior of lowess() using keywords 'fract', 'delta'
and 'iter'.

When x is not sorted, you need to use lowess(sort(x),y[grade(x)]).

@@@@keywords#Keywords
The following summarizes the lowess() keyword phrases which modify the
smoothing algorithm.  All have REAL scalar values and can be used with
'xpred'.
  Keyword      Value      Default     Description
  -----------------------------------------------------------------------
  fract:f     0 < f <= 1    2/3       Fraction of points used to compute
                                      each smoothed value
  delta:Delta 0 <= Delta x_range/100  x values within Delta of other x
                                      values have smoothed values
                                      computed by interpolation rather than
                                      additional regressions
  iter:m      integer m > 0  3        number of iterations of robust
                                      fitting

These defaults are the same as those in R.

The larger f is, the smoother ys will be.  This is because each weighted
regression is based on r data pairs, (x[j], y[j]), j = j1, j1+1, ..., j2
= j1+r-1, where r = max(2,round(f*n)).

Non-zero values of delta can result in faster fitting.  See below.

When there are tied x's, the value of ys can differ for different
orderings of the ties x's.

'fract' and 'delta' can be abbreviated to 'f' and 'del', respectively.

@@@@method#Method
lowess() uses iteratively reweighted least squares to fit a straight
line to data near each x[i].  The weight for x[j] depends on |x[j]-x[i]|
and, after the first iteration, on |y[j]-y_smooth[j]|, where y_smooth[j]
is the smoothed value from the previous iteration.  Larger distances and
larger residuals result in lower weights.  See the reference below for
details on the weights used.

ys[i] is computed from r pairs, (x[j], y[j]), j=j1,...,j2 = j1 + r - 1
and r = max(2, round(f*n)) with x[j1] <= x[i] <= x[j2], where j1 <=
n+1-r is chosen to minimize max(x[i] - x[j1], x[j2] - x[i]).

When these x[j]'s don't vary enough reliably to estimate a slope, ys[i]
is a weighted average of y[j], j1 <= j <= j2.

Some shortcuts are made:

When there are k tied x's, that is x[i] = x[i+1] = ... = x[i+k-1], the
regression computation is done only for x[i] and then ys[i+1], ...,
y[i+k-1] are set equal to ys[i].

When Delta > 0 and there are near ties, that is x[i1]-x[i] <= Delta, i1
> i, ys[i1] is computed by linear interpolation between ys[i] and ys[i2]
where x[i2] - x[i] > Delta (or between ys[i] and ys[n] when x[n]-x[i] <
Delta.

@@@@reference#Reference
You can find more information about the lowess() method in the following
reference:
  Cleveland, W. S. (1979) Robust locally weighted regression and
  smoothing scatterplots. J. Amer. Statist. Assoc. 74, 829-836.

The code used is adapted from ratfor subroutines lowess() and lowest()
by W. S. Cleveland obtained from statlib.

@@@@example#Example
  Cmd> irisdata <- getdata(irisdata, quiet:T) # Fisher Iris Data
  Read from file "/usr/libs/macanova/auxfiles/macanova.dat"

  Cmd> variety <- irisdata[,1]

  Cmd> x <- irisdata[variety==1,2] # I. setosa sepal length

  Cmd> y <- irisdata[variety==1,3] # I. setosa sepal width

  Cmd> plot(x,y,symbols:"\1",show:F)

  Cmd> addlines(lowess(sort(x),y[grade(x)]), show:F)

  Cmd> showplot(dumb:T,width:70,xlab:"Sepal length",ylab:"Sepal width",\
       title:"Iris Setosa Sepal width vs Sepal length with smooth")
                Iris Setosa Sepal width vs Sepal length with smooth
             +---+-------+------+------+-------+------+------+-------++
          4.5+                                                   o    +
             |                                                        |
             |                                            o           |
             |                                 o                      |
   S        4+                                                  .....o+
   e         |                                        o     ....      |
   p         |                             o      o ..o.....     o    |
   a         |           o          o  o     .......                  |
   l      3.5+                         o ..o.  o          o           +
             |           o      o     .o.  o   o      o               |
   w         |                ........ o   o                          |
   i         |   o ......o..o.         o                              |
   d        3+o..o.      o      o   o  o                              +
   t         |   o                                                    |
   h         |                                                        |
             |                                                        |
             |                                                        |
          2.5+                                                        +
             |       o                                                |
             +---+-------+------+------+-------+------+------+-------++
                4.4     4.6    4.8     5      5.2    5.4    5.6    5.8
                                   Sepal length

@@@@see_also#Cross references
See also regress().

@@@@____

====macanova*#general
%%%%
Type 'help(macanova)' for a description of what MacAnova is and a
summary of its features and history
%%%%
@@@@what_macanova_is#What MacAnova is
MacAnova is an interactive, programmable, multi-platform computer
program for matrix manipulation and statistical analysis.  It features
commands for the analysis of linear and generalized linear models, for
multivariate analysis, and for the frequency analysis of time series.
It is available for Apple Macintosh OS X (TM), Microsoft Windows (TM),
and Unix (TM)/Linux. .

MacAnova is controlled primarily by typing commands and not by selecting
items from menus.  Its command syntax is modeled after S and but differs
in many minor and some major ways.

@@@@help_and_usage#Help and usage
Type 'help' or 'help()' for a brief summary of how to obtain on-line
usage information and extensive help for all commands and most features.

@@@@glm_design_and_time_series#GLM design and time series
Type 'help(glm)', 'help(design)' or 'help(time_series)' for information
on analyzing linear and generalized linear models, experimental design
and time series analysis.

@@@@obtaining_macanova
                           Obtaining MacAnova
Executable versions of the Macintosh, DOS and Windows versions are
available through the MacAnova home page, with URL
  http://www.stat.umn.edu/macanova/macanova.home.html
Also there are source files and Portable Document Format (PDF) versions
of the User's Guide and other documentation.  These files are also
available by ftp from ftp.stat.umn.edu/pub/macanova and are mirrored
by statlib (http://lib.stat.cmu.edu/).

@@@@features
                                Features
Variables and operations
 + Named real, logical and character vectors, matrices and arrays, plus
   structures and graph variables
 + Coordinate labels for vectors, matrices and arrays
 + Usual arithmetic (+, -, *, /, ^ or **) plus modular division (%%) and
   bit manipulation (%&, %|, %^, %!)
 + Most operators and many functions work with structures, allowing
   analysis of non-rectangular data sets.
Help
 + On-line usage summaries and complete help for more than 300 topics
Descriptive statistics
 + Means, variances, medians, quartiles, extremes, skewness, kurtosis
 + Cross tabs and cell means and variances
 + Smoothing by LOWESS algorithm
Linear and generalized linear models
 + A linear model grammar with multiple error terms and shortcuts for
   polynomial and periodic regressions
 + Up to 95 variables of which 32 can be factors
 + On the fly transformations of dependent and independent variables
 + ANOVA, MANOVA and regression with optional weights
 + Robust ANOVA and regression
 + Logistic, probit and Poisson regression
 + Iterative proportional fitting
 + Branch and bound determination of best subset regression
 + Power and sample size functions for CRD and RBD
 + Residual plots and macros
 + Model coefficients, standard errors, contrasts
 + t-tests, confidence intervals
 + Weighted analyses
 + Expected mean squares
Matrix algebra
 + Matrix multiplication and inversion
 + Linear equation solution
 + Eigenvalues and relative eigenvalues
 + Cholesky, QR and SVD decompositions
 + Beaton sweep operator
 + Trace, diagonal, determinant, outer products, and other matrix and
   vector manipulations
Time series
 + Fast Fourier transforms
 + Convolution
 + Autoregression and moving average operators
 + Yule-Walker solver and its inverse
 + ACF to partial ACF and its inverse
 + Spectrum and cross-spectrum analysis, including multi-taper
   estimation
 + Time series plots
 + Frequency function plots
Multivariate analysis
 + MANOVA
 + Hierarchical cluster analysis
 + K-means cluster analysis
 + Macros related to discrimination and factor analysis
 + Varimax rotation
Design of experiments
 + Confounding 2 and 3 series factorials
 + Finding aliases in 2 and 3 series fractional factorials
 + Choosing generators and design points in 2 series fractional
   factorials
 + Canonical analysis of 2nd order response surface
 + Constrained maximization of quadratic functions
Random numbers and probabilities
 + Uniform, normal, Poisson and binomial pseudo-random number generators
 + Cumulative and inverse normal, chisquare, F, t, beta, gamma
 + Cumulative and inverse noncentral chisquare
 + Cumulative non-central F, beta and t
 + Cumulative poisson and binomial
 + Cumulative and inverse Studentized range
 + Cumulative and inverse Dunnett's t
Graphical features
 + Scatter plots, including several y's vs one x
 + Line and impulse plots
 + Box plots, histograms and stem and leaf displays
 + Interaction plots
 + Stepwise construction of graphs
 + Replotting with changed labels, bounds and tick marks
 + GRAPH variables encapsulating all the information in a graph
 + GRAPHWINDOWS, a structure containing GRAPH variables for all windows
Transformations
 + max, min, sum, prod, all operating on columns of matrices
 + Usual transcendentals
 + Rational functions
 + Ordering, ranking, sorting
Programmability
 + Macros used just like function, automatically searched for on
   external files when not loaded
 + Many built-in macros plus 4 files of loadable macros (general, time
   series, ARIMA, and design of experiments)
 + For and while loops, if, else, elseif, break
User functions
 + Dynamic loading and execution of user compiled code with call backs
   to MacAnova functions.

@@@@history
                                History
MacAnova was created in 1987 by Gary W. Oehlert of the Department of
Applied Statistics, University of Minnesota to provide for the design
and analysis of experiments on Macintosh microcomputers in a classroom
environment. It has been expanded and enhanced since 1991 by Christopher
Bingham, with the goal of using it in connection with applied
multivariate analysis and the frequency analysis of time series, as well
as general statistical computing.  Gary Oehlert programmed the interface
for versions that run under Unix/Linux GTK, Microsoft Windows, and
Mac OS X.
@@@@______

====macanova3*#
%%%%
Type help(file:"macanova.nws",macanova3) for a summary of improvements
of MacAnova3.3x over MacAnova2.4x.
%%%%
This topic, which summarized improvements of MacAnova3.3x and later over
MacAnova2.4x, has been moved to file macanova.nws, distributed with
MacAnova.  If this file is in the same directory or folder as MacAnova,
you can read the topic by typing help(file:"macanova.nws",macanova3).

====macanova_index*#
%%%%
Type help(macanova_index) to get information on the contents of file
macanova.hlp.
%%%%
File macanova.hlp is too large to have a useful annotated index.

You can get a list of all help topics in the standard help file
macanova.mac by
  Cmd> help(orig:T, "*")

help() keyword 'key' provides an easy way to get lists of help topics
related to specific areas
                                   Area of interest
  help(key:"anova",orig:T)     Analysis of variance
  help(key:"cat",orig:T)       Categorical data analysis
  help(key:"char",orig:T)      CHARACTER variables
  help(key:"combining",orig:T) Combining variables
  help(key:"compar",orig:T)    Comparing values
  help(key:"complex",orig:T)   Complex arithmetic
  help(key:"confide",orig:T)   Confidence intervals
  help(key:"control",orig:T)   Controlling MacAnova computations
  help(key:"descrip",orig:T)   Descriptive statistics and t-statistics
  help(key:"files",orig:T)     Use and format of files
  help(key:"glm",orig:T)       Linear and generalized linear model
                               analysis
  help(key:"general",orig:T)   Various issues including getting help and
                               testing the properties of variables
  help(key:"input",orig:T)     Entering data and inputting data from
                               files and the clipboard
  help(key:"logic",orig:T)     LOGICAL variables and operators
  help(key:"null",orig:T)      NULL variables
  help(key:"macros",orig:T)    Using and writing macros
  help(key:"matrix",orig:T)    Matrix algebra
  help(key:"missing",orig:T)   Missing values
  help(key:"multivar",orig:T)  Multivariate analysis
  help(key:"oper",orig:T)      Arithmetic and logical operations
  help(key:"ordering",orig:T)  Sorting and computing normal scores
  help(key:"output",orig:T)    Printing results and saving MacAnova
                               output in files
  help(key:"plotting",orig:T)  Drawing and modifying graphs
  help(key:"prob",orig:T)      Cumulative distribution functions and
                               their inverses; power computations
  help(key:"random",orig:T)    Random number generation
  help(key:"regress",orig:T)   Regression analysis
  help(key:"resid",orig:T)     Residual analysis
  help(key:"struct",orig:T)    Structures
  help(key:"syntax",orig:T)    MacAnova syntax; control words such as
                               'if' and 'while'
  help(key:"time",orig:T)      Time series analysis
  help(key:"trans",orig:T)     Mathematical transformations
  help(key:"variables",orig:T) Types and names of variables

You can omit keyword phrase 'orig:T' when the current help file is
macanova.hlp.

====macintosh%#general
%%%%
Type help(macintosh) for a summary of features special to MacAnova for
  Mac OS X.
%%%%
Summary of features special to the Mac OS X version.

MacAnova for Macintosh OS X is built using Carapace (see help topic
'carapace'), so all of the Carapace features are present on the
Macintosh.

Menus are slightly different on Mac OS X to conform with standard
Macintosh guidelines.  In particular, the About menu item and the
Quit menu item are under the program menu rather than the Help and
File menus.

The standard search paths in DATAPATHS include a "user" directory
(folder) and an "application" directory (see topic 'DATAPATHS').  On
Mac OS X, the user directory is "~/Library/Application Support/MacAnova"
where ~ is the user's home directory.  The application directory is the
SharedSupport folder that came with MacAnova; it must be in the same
folder as the MacAnova application.

MacAnova reads from  many files (macros, help, etc.).  For example,
MacAnova.mac.txt is the standard macro file.  If you put your own
modified copy of MacAnova.mac.txt into the user directory, then
MacAnova will read from your file instead of its own copy, because
the user directory comes before the application directory in the
search order.

====mac_classic%#general
%%%%
Type help(mac_classic) for a summary of features special to MacAnova for
  Mac OS 9.
%%%%
Summary of features special to the Mac OS 9 version.

@@@@windows_in_macintosh_version
                                Windows
There can be up to nine command/output windows.  Everything you type and
all character output goes in the frontmost one.  You can create a new
window using New Window on the Windows menu or Open on the File menu.
The latter loads the window with the contents of the file selected.  You
can switch between windows, close them or hide them using the Windows
menu.  You can print all of a window or a selection from a window by
selecting Print Window or Print Selection on the File menu.  You can
save their contents as files on disk by selecting Save Window or Save
Window As on the File menu.

There are eight high resolution graphics windows plus two panel windows,
Panel 1-4 and Panel 5-8, which display the other graph windows in
miniature.  You can switch between graphics windows, close them or hide
them using the Windows menu.  Any graphics window including the panel
windows can be printed using Print Graph... on the File menu or copied
to the clipboard for pasting into the Scrapbook or other application
using Copy on the Edit menu.  You can direct a plot to graph window i by
plotting keyword phrase 'window:i', where 1 <= i <= 8.  'window:0' puts
the graph in the window most recently written in.

You can display any graph window by pressing Command+1, Command+2, ...,
Command+8 or Command+F1, ..., Command+F8, and display panel windows by
Command+G.  Command+G also switches to the other panel window when a
panel window is displayed.

All windows have a close box in the upper left corner, a resizing box in
the lower right corner, and a zoom box in the upper right corner.
Output windows also have a scroll bar for moving backward and forward
through output.

@@@@executing_commands
                          Executing a command
MacAnova recognizes a command as being ready to execute only if the
cursor is at the end of the line when you hit Return, or if you hit
Enter (see next paragraph).  Of course, as in all versions, the line
will not be accepted as complete if there is any '{' unmatched by a
corresponding '}' or if there is an unfinished quoted string
started by '"'.

@@@@enter_key#Enter key
The Enter key is not equivalent to Return but might be considered an
"execute" key.  It behaves differently depending on whether you have
selected text before the prompt in the output window.  Command+Return or
Shift+Return are both equivalent to Enter.

  (a) If nothing is selected with the mouse in the output window, Enter
  is equivalent to moving the cursor to the end of the command line and
  pressing Return.  This causes the command on that line to be executed
  unless there is an incomplete quoted string or unbalanced curly
  brackets ({...}).  This is particularly useful when editing a command
  about to be executed.  No matter where in the line the cursor is,
  Enter causes the edited command to be executed, while Return does not
  initiate execution unless the cursor is at the end of the line

  (b) If you have used the mouse to select text before the current
  prompt, Enter causes it to be copied to the end of the current
  command line, followed by Return.  Except when there are unbalanced
  curly brackets or an incomplete quoted string, the current command
  line is then executed.  This makes for very easy re-execution of
  commands, possibly after editing them in place.

Item Copy and Execute (or Execute, when nothing is selected in the
output window) on the Edit menu does the same thing as Enter, as does
pressing Command+\ or key F6.

@@@@history_of_commands
                      History of previous commands
Typed commands are automatically saved in an internal "history" list.
You can move through this list, inserting previous commands after the
prompt, using items Up History and Down History on the Edit menu.

By default, MacAnova saves the most recent 100 lines.  To change this,
say, to 150, type 'setoptions(history:150)'.  See topics setoptions(),
'options'.

@@@@up_and_down_history
                          Up and down history
Pressing F7 or the key combination Option+up-arrow is equivalent to
selecting menu item Up History.  Pressing F8 or Option+down-arrow is
equivalent to selecting Down History.

Command+Option+up-arrow retrieves the oldest saved command.
Command+Option+down-arrow reinserts whatever you had originally typed,
if anything, before recalling earlier commands.

@@@@moving_in_window
                        Moving around the window
Arrow keys move the cursor as you would expect.  Command+B (Back) and
Command+F (Forward) are equivalent to the left- and right-arrow keys.
There is no equivalent to the up- and down-arrow keys.

Pressing the Option key while pressing a left- or right-arrow key moves
backward or forward one "name" (stretch of characters that are legal in
names).  Pressing the Option key while pressing an up- or down-arrow key
inserts previous commands at the prompt similar to items Up History and
Down History on the Edit menu.

Pressing the Command key while pressing an arrow key moves the cursor to
the start or end of the line (left- or right-arrow) or the top or bottom
of the window (up- or down-arrow).  Repeated use of Command+up or
Command+down-arrow scrolls through the window, moving the cursor as it
goes.

Pressing the Shift key while using an arrow key selects whatever is
between where you start and where you end.

@@@@windows_menu_shortcuts#Windows menu shortcuts
Command+A (Go To Prompt on the Windows menu) moves the cursor to the
start of the current command line, just after the current prompt.

Command+E (Go To End on the Windows menu) or End on suitable keyboards
moves it to the end of the current command line at the very end of
window.

Command+T (Scroll To Top on the Windows menu) or Home scrolls to the Top
of the current command/output window.  Command+U (or Page Up) scrools
back a screenful.  Command+D (or Page Down) scrolls forward a screenful.
These do not move the cursor.

@@@@file_names
                         Specifying file names
When you use "" as the file name in any command requiring one (for
example vecread("")), the usual Macintosh scrolling dialog box lets you
select the file.  You can also use an explicit file or "path" name.  In
the latter case, if the name does not contain ':' (which would identify
it as a "path" name), MacAnova will look for it first in the default
Folder (see topic 'files') and then in the Folders specified in pre-
defined CHARACTER vector DATAPATHS.  See topics 'file_names',
'DATAPATHS', adddatapath(), 'customize'.

@@@@help
                                  Help
Selecting item Help on the Apple menu is equivalent to typing 'help()'.
If a word, say 'matrix', is selected in the window, item Help is
equivalent to 'help("matrix").  Command+H or the Help key does the same.

@@@@interrupting
                              Interrupting
Command+. (period) or Command+I may be used to interrupt an operation or
output.  Depending on the operation it may not be recognized
immediately.

@@@@file_menu
                               File menu
Open (Command+O) creates a new output window and reads a file into it.
It might, for example contain output from a previous MacAnova session.

Save (Command+S) and Save As write the current command/output window to
a file.

Page Setup and Print/Print Selection/Print Graph (Command+P) do what you
would think they should do.

Interrupt (Command+I) is equivalent to pressing Command+. (period) (see
above).

Go On resumes computing after a graphing command with keyword phrase
'pause:T'.  See topic 'graph_keys'.

Save Workspace (Command+K) and Save Workspace As invoke save()
(asciisave() if asciisave() was used previously).  See save() and
asciisave().

Open Batch File (Command+Option+O) is equivalent to 'batch("")'.  See
batch().

Spool Output to File (Command+Option+S) is equivalent to 'spool("")'.
If a spool file has previously been specified this menu item will be
Stop Spooling or Resume Spooling and is equivalent to 'spool()'.

@@@@edit_menu
                               Edit menu
In the output/command window you can use Undo/Redo (Command+Z), Cut
(Command+X), Copy (Command+C), and Paste (Command+V) in the usual way.
For a graph window only Copy is active.

Copy to End (Command+/) copies the current selection to the end of
the command line without putting it on the Clipboard.

Copy and Execute/Execute (Command+\) is equivalent to pressing Enter
(see above) in the output command window.

Up History inserts the previously typed command after the prompt.
Repeated selection of Up History successively inserts older and older
commands.  It is equivalent to pressing the Option and up-arrow keys.

Down History moves forward through previously saved commands, inserting
them after the prompt.  It is equivalent to pressing the Option and
down-arrow keys.

Function keys F1, F2, F3, F4, F5, F6, F7 and F8 are equivalent to
Undo/Redo, Cut, Copy, Paste, Copy To End, Execute (Copy and Execute), Up
History and Down History, respectively.  Enter, Shift+Return and
Command+Return are additional keyboard short cuts for Execute.

@@@@windows_menu
                              Windows menu
This menu allows you to close or hide a window (Close and Hide), create
a new output/command window (New Window or Command+N), select a graph
window (Graph 1, Graph 2, ... Graph 8, Panel 1-4 and Panel 5-8), select
an output command window by name, and move around the output/command
window (Scroll To Top, Go To End, Go To Prompt, Page Up, Page Down).

@@@@command_menu
                              Command menu
The last 8 items are pre-defioned commands that are inserted in the
output/command window.  You can also select them by pressing Command+
+Option+1, ..., Command+Option+8.

Edit Commands... allows you to edit or replace any or all of the 8
commands.  Since each command can be a macro, this allows a great deal
of flexibility.

@@@@options_menu
                              Options menu
Significant Digits, Output Formats, Random # Seeds, Angle Units, GLM
Options, Batch Options and Other Options allow you to set many of the
items that can be changed by setoptions().

@@@@font_menu
                               Font menu
Size allows you to change the font size of the text in the current
output/command window.

The remaining items are the names of fonts you can select for the text
in the current output/command window.  You should probably restrict
your choices to non-proportional (equal character width) fonts such as
Monaco or Courier.  The default font is McAOVMonaco 9, a modified form
of Monaco 9.  Courier 18 may be preferable for use with an overhead
projector.  You can also change fonts using setoptions() using keywords
'font' and 'fontsize'.  See topic 'options'.

@@@@other_information
                           Other information
MacAnova can "background", that is it will continue running when you
switch to another application under System 7 or when you are using
Multifinder under earlier systems.

Option+'<', Option+'>' and Option+'=' are recognized as equivalent to
'<=', '>=', and '!=', respectively.  Option+'\' and Option+'|'
(Option+Shift-'\') are recognized as equivalent to '<<' and '>>',
respectively.

The shell() command and special treatment of lines starting with '!' is
not available on the Macintosh.  On System 7 or later, you can run other
programs just be starting them.  On SYstem 6 you can do the same using
Multifinder.  On all systems you can run Desk Accessories from within
MacAnova.

Files produced by save() in all Macintosh versions 3.xx and 4.xx, but
not 2.xx, can be restored.  However, files produced by asciisave()
should restore correctly.

Color is not supported under MacAnova except in so far as the system
provides it automatically for all applications.

====macro()#macros,control,syntax
%%%%
macro(text [, dollars:T, inline:T or F ,notes:Notes]), text a CHARACTER
  scalar, Notes CHARACTER scalar or vector
%%%%
@@@@usage_with_example#Usage with example
macro(Text) creates a macro from the commands contained in the CHARACTER
variable or quoted string Text.  Text can also be an existing macro.

Here is a short example of the use of macro().

  Cmd> vhat <-\
    macro("@x <- argvalue($1,\"argument 1\",\"real matrix nonmissing\")
    @n <- nrows(@x); @p <- ncols(@x) #get dimensions
    @x <- @x - sum(@x)/@n # compute residuals from mean
    @v <- if (@n > 1){(@x %c% @x)/(@n*(@n-1))}else{
        matrix(rep(0,@p*@p),@p)} # 0 matrix when n = 1
    delete(@n,@x,@p) # cleanup
    @v")

vhat(x) returns S/n, where S is the sample variance/covariance matrix of
matrix x.  See topics 'macros', 'macro_syntax' and argvalue() for
interpreting the text.

@@@@quotes_and_backslashes#Quotes and backslashes
When you use macro() to define a macro, you should type any quotes
'"' as '\"', as in the example.  Similarly to include a backslash '\'
you must type '\\'.  In particular, quoted quotes in a macro must
be typed as '\\\"' as in
  Cmd> quotedecho <- macro("print(\"\\\"$0\\\"\")")

  Cmd> quotedecho(The answer is 42)
  "The answer is 42"

@@@@dollars_keyword#Keyword 'dollars'
macro(Text,dollars:T) creates a macro from Text, adding "$$" to every
temporary name (name starting with '@') that (a) is not in a quoted
string, (b) is not in a comment starting with '#' and (c) does not
already end in "$$".  When the macro is executed, "$$" is replaced by a
2 digit number unique to the particular macro invocation so that the
actual name is unique to the macro.  The length of any temporary name
you use must be no more than 10 characters, counting '@'.  The following
appends '$$' to all temporary variable names in vhat:

  Cmd> vhat <- macro(vhat, dollars:T)

The first line of vhat now starts '@x$$ <-' instead of '@x <-.  See
topic 'macro_syntax' for more information about using '$$' in macros.

@@@@notes_keyword#Keyword 'notes'
You can attach explanatory notes to a macro using keyword phrase
'notes:Notes', where Notes is a CHARACTER vector.  See topic 'notes' for
details.

@@@@inline_keyword#Keyword 'inline'
macro(Text,inline:F [,dollars:T]) marks the macro being created as one
to be expanded out-of-line instead of having the expansion inserted into
the input line.  This primarily means that the macro will be freshly
expanded every time it is encountered, even on multiple trips through a
loop.  An instance of an in-line macro is expanded just once.  See topic
'macros'.  inline:T marks the macro as to be expanded in-line, even if
the value of option 'inline' is False.  See subtopic 'options:"inline"'.
You can mark an existing macro myMacro() to be expanded out-of-line by

  Cmd> myMacro <- macro(myMacro, inline:F)

@@@@nonstandard_characters#Nonstandard characters
Within quotes ("..."), any characters other than "\n" and "\t" whose
ASCII codes are either 127 or less than 32, are replaced by their
escaped octal representation of form \nnn.  For example,
  Cmd> myplot <- macro("chplot($1,$2,symbols:\"\001\",$K)")
  Cmd> myplot <- macro("chplot($1,$2,symbols:\"\x01\",$K)")
and
  Cmd> myplot <- macro("chplot($1,$2,symbols:\"\\001\",$K)")
are completely equivalent.

Non-standard characters with ASCII codes >= 128 are not treated
specially.  For example,
  Cmd> myplot <- macro("chplot($1,$2,symbols:\"\201\",$K)")
  Cmd> myplot <- macro("chplot($1,$2,symbols:\"\x81\",$K)")
are equivalent, producing a macro containing whatever character has
ASCII code 129, which has a computer specific interpretation.

@@@@see_also#Cross references_topic_macros
See topic 'macros' for details on writing macros, including the use of
special symbols '$0, '$1', '$2', ..., '$N', '$V', '$v', '$K', '$k', '$S'
and '$$'.

@@@@examples#Examples
Examples:
  Cmd> median <- macro("describe($1,median:T)")
  Cmd> myread <- macro("matrix(vecread(\"$1\"),$2)'") #note transpose
  Cmd> greetings <- macro("print(\"\\\"Hello\\\"\")")
  Cmd> xlogx1 <- macro("@x <- $1; @x*log(@x)")
  Cmd> xlogx2 <- macro("@x$$ <- $1; @x$$*log(@x$$)")
  Cmd> xlogx3 <- macro("@x <- $1; @x*log(@x)", dollars:T)

median(x) would compute the medians of the columns of x.  See
describe().

y <- myread(family.dat,23) would create a matrix with 23 columns from
data from file family.dat, assumed to have a total of n*23 data items
arranged in n rows.

greetings() prints "Hello", complete with the quotation marks.

xlogx1(x), xlogx2(x) and xlogx3 all compute x*log(x).  However, use of
xlogx1 might lead to a problem if some other macro also used @x as a
temporary variable.  xlogx2 avoids this problem because the temporary
variable name @x$$ will be expanded to @x51, say, a name that should not
conflict with any other temporary name.  xlogx3 is identical to xlogx2
because each instance of @x is converted to @x$$.
@@@@______

@@@@see_also#Cross references
See also topics 'macros', 'macro_syntax', macroread(), macrowrite().
@@@@______

====macro_files%#macros,files,input,output
%%%%
Type help(macro_files) for information on the file format expected by
  macroread().
%%%%
@@@@introduction#Introduction
This topic describes the format of a file to be read by macroread().
See topics 'data_files', 'vecread_file' and 'matread_file' for
information on data files, and topic 'files' for more technical
information on file names, default directories or folders, and
abbreviated file names of the form "~/filename".

@@@@general_description_of_file_format#General description of file format
A file that can be read by macroread() must be a plain text or ascii
file.  If you create it in a word processor, be sure to save it as a
text or ascii file.  On the file can be any number of macros, each with
a header line, followed by optional comment lines and macro text lines.
The header line must contain keyword MACRO and may contain one or more
keywords INLINE, OUTOFLINE, NOTES, ENDED or DOLLARS.  MACRO must be the
first keyword but the order of others is irrelevant.

@@@@formats_for_macros#Formats for macros
There are two possible formats for macros that can be read by
macroread().  Both can include descriptive notes (see topic 'notes').

Form A is terminated by a special line:
   Name MACRO [other keywords]
   ) 0 or more descriptive comment lines starting with ')'
   ) .......
   Line 1 of macro
   . . . . .
   Line Nlines of macro
   %Name%

Form B, requires a count of the lines and is considered obsolete:
   Name Nlines MACRO [other keywords]
   ) 0 or more descriptive comment lines starting with ')'
   ) .......
   Line 1 of macro
   . . . . .
   Line Nlines of macro

Name is the macro name to be searched for.  Case is ignored in searching
for the name, so that macroread(FileName,"mymacro") will find mymacro(),
MyMacro(), or MYMACRO(), for example.

The text of the macro immediately follows the header and comment lines.

In form A, the line immediately after the last line of macro text must
be %macroname%, where macroname must be identical, including use of
upper and lower case letters, to the name on the name line.

In form B, Nlines must be an integer and there must be exactly Nlines of
text.  The count includes lines starting with "#" but not the
descriptive comment lines, if any.

It is good practice to include both header comment lines starting with
")" and macro comment lines starting with "#" describing the usage of
the macro.  See also macrousage().

@@@@empty_macro#Empty macro
It is permissible for there to be no lines of macro text (%macroname%
immediately following comment lines for form A or Nlines = 0 for Form
B).  When macroread() reads such a "macro", only the descriptive
comments are printed (if 'quiet:T' is not present).  It is a useful
convention to make the first macro on a file have 0 length with the
header describing the contents of the file, since then
'macroread(FileName)' will print the contents.

                   Optional keywords on the name line
@@@@OUTOFLINE_on_name_line
OUTOFLINE:
When the name line is of the form
   Name MACRO OUTOFLINE [other keywords]
or
   Name MACRO Nlines OUTOFLINE [other keywords]
the macro will be marked so that it will always be expanded out-of-line.
When INLINE appears instead of OUTOFLINE, it will not be so marked.
Simply OUT or IN can be used instead of OUTOFLINE or INLINE.  Since in-
line expansion is the default, INLINE is never required.

@@@@NOTES_on_name_line
NOTES:
When the name line is of the form
   Name MACRO NOTES [other keywords]
or
   Name MACRO Nlines NOTES [other keywords]
the macro should be followed by a data set named "Name$NOTES" containing
a CHARACTER vector of descriptive usage notes.  See topic 'matread_file'
for the format.

@@@@DOLLARS_on_name_line
DOLLARS:
When the name line is of the form
   Name MACRO DOLLARS [other keywords]
or
   Name MACRO Nlines DOLLARS [other keywords]
'$$' will be appended to any temporary variable names (names starting
with '@') that don't already end with '$$'.  When DOLLARS is on the name
line of macro myMacro(), macroread(fileName,"myMacro") is equivalent to
macro(macroread(fileName,"mymacro"),dollars:T).  See topics macro() and
'macro_syntax'.

@@@@ENDED_on_name_line
ENDED:
When a form B name line has the form
   Name MACRO Nlines ENDED [other keywords]
it signals that the macro is followed by a line starting '%macroname%',
where 'macroname' exactly matches the name on the name line.  In some
cases, this can prevent read(), matread() or macroread() from
erroneously recognizing a line of the macro as the header for another
macro.  ENDED may also be used on form A macros, but is unnecessary
since they are required to have an ending line.

@@@@LOCKED_on_name_line
LOCKED:
When the name line is of the form
   Name MACRO LOCKED [other keywords]
or
   Name MACRO Nlines LOCKED [other keywords]
and the result of macroread() or read() is assigned to create a macro,
that macro will be locked.  See topic 'locks'.

  Cmd> doit <- macroread("macrofile.txt","doit")
  doit  MACRO LOCKED

  Cmd> list(doit)
  doit            MACRO  (in-line) (locked)

@@@@end_of_macros_code#End-of-macros line
A line starting _E_N_D_O_F_M_A_C_R_O_S_ terminates the reading of macros
or data from a file.  You can put help information for the macros after
this line.  See file macanova.hlp for a description of the required
format for the help that would follow this line.

@@@@example_file#Example file
Example of macro file containing a 0 length, information only, macro and
three genuine macros:

   info      MACRO
   ) This file contains macros median(), rm(), and means()
   %info%

   median    MACRO
   ) median(x) computes medians of columns of x
   # usage: median(x) [it's helpful to include usage in body of macro]
   describe($1,median:T)
   %median%

   rm        2 MACRO
   ) rm(a,b,...) alias for delete for Unix/Linux lovers
   # usage: rm(a,b,...) equivalent to delete(a,b,...)
   delete($0)

   means      MACRO NOTES DOLLARS
   ) means(x1,x2,...) computes means of vector arguments
   # usage: means(x1,x2,...) computes means of vector arguments
   @args <- structure($0) # make structure of all arguments
   for(@i,1,$N){
       if(!isvector(@args[@i])){
           error("Arguments to macro $S must be vectors")
       }
   }
   @result <- rep(0,$N) #create vector of right length
   for(@i,1,$N){
       @result[@i] <- sum(@args[@i])/nrows(@args[@i])
   }
   @result
   %means%

   means$NOTES  CHARACTER
   ) Two lines of usage notes for macro means()
   means(x1,x2,...) computes means of its vector arguments, returning
   them in a vector.
   %means$NOTES%

   _E_N_D_O_F_M_A_C_R_O_S_

The _E_N_D_O_F_M_A_C_R_O_S_ line is optional but recommended.  It must
be used if anything else other than data sets, for example help
information, follows the macros in the file.
@@@@______

Note: Form A was new with Version 4.04 of MacAnova.  Keywords ENDED and
DOLLARS were new in February 1999.

====macro_syntax%#macros,syntax,control
%%%%
Type 'help(macro_syntax)' for information on how to write macros.
%%%%
@@@@introduction#Introduction
This topic presumes familiarity with topic 'macros'.  It describes
the use of comments in macros, how values are returned, the special
symbols that may be used in macros and gives some tips on writing
robust and efficient macros.

Topics include Macro Self-Documentation, The Value of a Macro,
Referencing Macro Arguments, Use of Temporary Variables, Expansion of
Other Special Symbols Containing '$', Recursive Use of Macros, Tips For
Good Macro Writing, and Functions Useful in Macros

@@@@self_documentation
                        Macro Self-Documentation
Often the first few lines of a macro are comments ("#" at the start of
the line) which describe how the macro is used.  You can use command
macrousage() to print such comment lines.  When you write a macro, it is
good practice to include such lines.

@@@@value_of_macro
                          The value of a macro
The last expression appearing in a macro is returned as its value.  If
this expression is the name of an "invisible" variable (name starting
with '_' or '@_') the macro value can be assigned or used in an
expression but will not be printed.  If no value is to be returned, the
macro should end with ';;' which ensures the value returned is NULL.

In addition, you can use 'return(Value)' almost anywhere in a macro to
immediately leave the macro, returning Value as the value of the macro.
Value may be a constant, expression or variable.  'return()' and
'return' without parentheses are equivalent to 'return(NULL)'.  See
topic 'return'.

See below for the use of delete() with keyword phrase return:T to return
a temporary variable as value.

@@@@referencing_macro_arguments
                      Referencing macro arguments
In the text of a macro the place holders '$1', '$2', ... are used to
refer to argument 1, argument 2, ... .  When the macro is executed,
MacAnova examines its text and substitutes the appropriate argument,
almost exactly as typed, for any such place holder.  It then executes
the commands as if they had been typed at the keyboard.  For example, if
the first argument to a macro is '3+4', '@a <- $1' gets expanded to '@a
<- 3+4'.

When a macro references a missing argument (for example, $3 when there
are only two arguments) it usually terminates immediately with an error
message.  When, however, a missing argument appears in a quoted string
('print("$3")' when there are only two arguments) it is "expanded" to
nothing ('print("")').  When you use place holders of the form '$01',
'$02', ..., with a leading 0 for the number, then a missing argument is
expanded to NULL outside of a quoted string (see topic 'NULL').  This
may or may not result in an error message if the argument is used, but
you can test the value using one or more of the isxxxx() functions (see
below).

@@@@quoted_string_argument#Quoted string argument
When an argument which is itself a quoted string, possibly containing
backslashes ('\'), is referenced in the macro as part of a quoted
string, then all instances of '"' and '\' in the argument are changed to
'\"' and '\\'.  For example, in a macro, 'print("$1")' expands to
'print("3+4")' when the first argument is '3+4' but expands to
'print("\"foo\"")' when the first argument is '"foo"'.

@@@@using_temporary_variables
                       Use of temporary variables
It is good practice to use temporary variables (names starting with '@')
in macros so they will be deleted automatically just before the next
prompt.  You can also append '$$' to names to create a name that should
be unique to the macro (see below).  When you use 'dollars:T' as an
additional argument to macro() in creating a macro, '$$' will be
automatically appended to all temporary names not already ending in
'$$'.  This also happens when a macro with keyword DOLLARS on its header
line is read from a file.

Because temporary variables are not deleted until the next prompt, it is
often a good idea to delete them before exiting a macro, except for a
result being returned, of course.  To delete a variable, say '@result',
whose value is to be returned, the last command in the macro should be
delete(@result,return:T).  @result will be deleted but its value will
still be returned.  See delete().

@@@@invisible_variable#Invisible variable
Occasionally you may want to create a non-temporary "invisible"
variable, that is, one that is not normally listed by list() or
listbrief().  You do this by assigning a name starting with '_' such as
'_x'.  One use for this is to create a variable to be used by several
related macros but not directly referenced by the user.  See also list()
and listbrief().  A temporary variable is "invisible" if its name starts
with '@_', say '@_x'.  See topic 'variables:"invisible"'.

You can return an "invisible" result by

  delete(@result,return:T,invisible:T)

@@@@dollars_expansion
           Expansion of other special symbols containing '$'
In a macro, certain symbols starting with '$' have a special meaning.
Although they would be errors outside a macro, in a macro these symbols
are "expanded", that is, something is substituted for them in the text
of the macro.  In brief, these symbols are as follows:

  Symbol     Expanded value
  $0         The complete comma-separated list of macro arguments.
  $N         The number of macro arguments = 1 + (number of separating
             commas) except when the agument list is empty, when the
             value is 0
  $V         A comma separated list of all macro arguments that are not
             keyword phrases.
  $v         The number of macro arguments that are not keyword phrases.
  $K         A comma separated list of all macro arguments that are
             keyword phrases.
  $k         The number of macro arguments that are keyword phrases.
  $A         A CHARACTER vector whose elements are the character strings
             specifying the arguments, that is, vector("$1","$2",...).
  $S         The name of the macro.
  $$         Expands to a unique 2 digit number, 00, 01, ..., 49 in out-
             of-line macros and 50, 51, ..., 99 in in-line macros.

$N, $V, $v, $K, $k, $S and $A are not treated specially when they are
preceded or followed by a character that could be part of a variable
name.  For example, str$N would be interpreted as component N of
structure str (see 'structures') and $Na would not be changed and would
probably result in an error.

@@@@dollars_details#Dollars details
Here are fuller explanations or examples of the use of these special
symbols.  In all the following we assume the symbols are in a macro
invoked by mymacro(x, title:"Hello Dolly",run(5),new:T).

$0 (full list of arguments):
  In the example $0 is replaced by 'x,title:"Hello Dolly",run(5),new:T'.
  $0 is particularly useful in defining "aliases" of standard commands.
  For example,
   Cmd> dir <- macro("list($0)")
  defines macro dir() which is used identically to list().

  When $0 appears in a quoted string, all instances of '"' or '\' in any
  macro argument are prefixed by '\'.  In the example, "$0" is replaced
  by "x, title:\"Hello Dolly\",run(5),new:T".

$N (number of arguments):
  In the example, $N is replaced by '4'.

$V (list of non keyword arguments):
  In the example, $V is replaced by 'x,run(5)'.  When $V is used within
  double quotes, any instances of '"' or '\' are expanded as for $0.

$v (number of non keyword arguments):
  In the example, $v is replaced by '2'.

$K (list of keyword arguments):
  In the example, $K is replaced by 'title:"Hello Dolly",new:T'.  This
  is useful for passing on all the keywords to a function invoked by the
  macro.  See pre-defined macro colplot() for an example of the use of
  $K.  When $K is used within double quotes, any instances of '"' or '\'
  are expanded as for $0.

$k (number of keyword arguments):
  In the example, $k is replaced by '2'.

$A (CHARACTER vector of all arguments in quotes):
  In the example $A is replaced by vector("x","title:\"Hello Dolly\"",
  "run(5)","new:T").  To print argument 3 to a macro as it appeared in
  the call, instead of print("$3"), you might use print($A[3]).  In
  the example this would print 'run(5)'.  Any instances of '"' or '\' in
  the arguments are replaced by '\"' and '\\'.  When $A is part of a
  quoted string, it is not expanded.

$S (name of macro):
  In the example, $S is replaced by 'mymacro' whether or not it is in
  quotes.

$$ (number unique to macro expansion):
  This expands to a unique two digit number, even in a quoted string.
  The particular integer that replaces $$ remains the same throughout an
  invocation of the macro, but is incremented by 1 for each macro in
  which $$ is used.  It allows you to create temporary variable names
  that are specific to a particular execution of a macro.  For example,
  '@A$$ <- 3' might become '@A52 <- 3' or '@A57 <- 3' depending on when
  and where the macro is executed.  As long as you don't use any
  temporary names ending in two digits, rigorous use of '$$' eliminates
  the possibility of "collisions" between temporary variables names in
  different macros.

  In a macro expanded in-line, the value of $$ starts at 50.  If $$
  reaches 100, all macros abort.  In a macro expanded out-of-line, the
  value of $$ ranges from 0 to 49 and all macros abort if it reaches 50.
  This behavior limits the depth to which macros can be nested or
  recursive macros can call themselves

  Note that each invocation of a macro expanded in-line in a loop will
  have the same value for $$ since it is expanded only once, the first
  time through the loop.  This will usually be the case for macros
  expanded out-of-line, too, but it cannot be guaranteed.

@@@@recursion
                        Recursive use of macros
A macro may invoke itself directly or indirectly up to a maximum depth
of 50, provided some test is included to avoid infinite recursion.  In
practice, current limitations of the parser limit the maximum depth to
around 20.  If you need greater depth, you may be able to attain it
using evaluate().

@@@@tips
                      Tips for good macro writing
Because macro arguments are expanded literally, their place holders
should usually be enclosed in parentheses when used in expressions.
For example, use '($1)*($2)' rather than '$1*$2'.

When a macro argument is referred to more than once in a macro it should
usually first be copied to a temporary variable.  For example, a macro
to compute a mean should be defined by
  Cmd> mean <- macro("@x <- $1;sum(@x)/dim(@x)[1]",dollars:T)
rather than by the somewhat simpler
  Cmd> mean <-  macro("sum($1)/dim($1)[1]")
If the latter definition is used, 'mean(boxcox(x[,vector(1,2,4)],.5))'
would result in boxcox(x[,vector(1,2,4)],.5) being evaluated twice.

When a macro is not intended to return a value, end it with ';;'.  For
arcane reasons, this helps MacAnova allocate memory more efficiently.

Use error() to print any messages describing errors that terminate the
macro.  It works similarly to print() but automatically prefaces the
message with "ERROR: ", appends " in macro xxxxx" and produces an error
condition that terminates the macro and returns to the prompt level.

If the error message contains the macro name (dollar symbol $S), use
keyword phrase 'macroname:F' with error() as in
  if ($v != 2){error("$S requires 2 non-keyword arguments",macroname:F)}

See topic error() for more information.

If you use anova(), regress() or any other GLM command in the macro and
you do not want to destroy information from a previous GLM command,
bracket the use of a GLM command by pushmodel() and popmodel() as in the
following fragment:
  if (pushmodel(canpush:T)){pushmodel()}
  anova(@model, silent:T)
  if (popmodel(canpop:T)){popmodel()}

If you want to have the macro run on versions dating prior to the
introduction of pushmodel() and popmodel(), use
  if (alltrue(isfunction(pushmodel),pushmodel(canpush:T))){pushmodel()}
  anova(@model, silent:T)
  if (alltrue(isfunction(popmodel),popmodel(canpop:T))){popmodel()}

@@@@useful_functions
                       Functions useful in macros
There are several functions whose primary usefulness is within a macro.

keyvalue() interprets arguments that are keyword phrases list and check
their values for appropriateness.

argvalue() lets you access a non-keyword argument while checking it for
appropriateness.

anymissing(), isdefined(), isscalar(), isvector(), ismatrix(),
isarray(), isfactor(), isreal(), ischar(), islogic(), isnull(),
isgraph(), isstruc(), ismacro(), isfunction(), isnumber() and isname()
are also useful in checking whether an argument is suitable.

modelvars(), modelinfo(), varnames(), xvariables() and xrows() allow a
macro to do sophisticated computations based on the results of a
previous GLM command.

pushmodel() and popmodel() allow you to save and restore results from a
previous GLM command.

setodometer() is helpful in looping over all combinations of factor
levels.

@@@@example#Example
Here is a fragment that might be in a macro whose first argument should
be a REAL scalar and second argument should a CHARACTER vector, and
which should recognize keywords 'down' with T or F for value and 'power'
with positive REAL scalar value.  'down' is optional with default F and
'power' is required.

  @n <- argvalue($1,"sample size","positive integer scalar")
  @labs <- argvalue($2,"labels","character vector")
  @down <- keyvalue($K,"down","TF",default:F)
  @power <- keyvalue($K,"power","positive number")
  if (isnull(@power)){
     error("keyword 'power' is required by $S",macroname:F)
  }
  ....

When the value of an argument doesn't have the specified properties,
argvalue() and keyvalue() immediately terminate the macro.

@@@@see_also#Cross references
See macroread() for examples of macros.
@@@@______

====macroread()#macros,files,input
%%%%
mymacro <- macroread(FileName,macroName [,quiet:T or F, echo:T or F,\
  silent:T, printname:F, notfoundok:T, nofileok:T, prompt:F,\
  badkeyok:T]), FileName and macroName CHARACTER scalars; FileName can
  also be CONSOLE or have the form string:charVal where charVal is a
  CHARACTER scalar or vector.
%%%%
@@@@usage#Usage
mymacro <- macroread(FileName,macroName) searches the named file for a
macro whose name matches macroName.  If the macro is found, it is read
and made available under the name mymacro().  FileName and macroName
must be quoted strings or CHARACTER scalars.

Usually the name to the left of '<-' will be the same as the name of the
macro read as in
  Cmd> density <- macroread("densities.mac","density")

In searching the file for a matching name, case is ignored so that, so
that macroread(FileName, "mymacro") will find mymacro(), MyMacro(), or
MYMACRO(), for example.  See topic 'macro_files' for a description of
the required file format.

In a version with windows, when FileName is the null string "", you
will be prompted to select the file using a dialog box.

The header and comment lines are normally echoed to output, but this can
be suppressed by keywords;  see below.

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

  Cmd> doit <- macroread("macrofile.txt","doit")
  doit  MACRO LOCKED

  Cmd> list(doit)
  doit            MACRO  (in-line) (locked)

@@@@macro_name_omitted#Macro name omitted
mymacro <- macroread(FileName) with no macro name reads the first macro
on the file.  The first non-empty, non-blank line in the file is assumed
to be the start of the macro as described in topic 'macro_files'.  It is
an error if it is not in the right format for the first header line of a
macro or data set.

@@@@assignment_of_result#Assignment of result
Just reading a macro does not make it available; you must assign the
value of macroread() using '<-'.  You can usually use getmacros() to
simultaneously read a macro and make it available.

@@@@getmacros_macro#Macro getmacros()
When you are reading a macro from one of the standard macro files
(arima.mac, design.mac, graphics.mac, macanova.mac, math.mac,
mulvar.mac, regress.mac and tser.mac) pre-defined macro getmacros() is
more convenient to use than macroread().  An example of its use is

  Cmd> getmacros(covar)

This replaces to 'covar <- macroread("macanova.mac","covar")', except
that you don't even need to know which file covar() is located in.

@@@@automatic_search_for_macros#Automatic search for macros
Use of macroread() or getmacros() is sometimes not necessary, since the
default behavior of MacAnova is to search the files in MACROFILES (see
getmacros()) for any undefined macro you try to use.  For example, even
if macro covar() has not previously been read from file "MacAnova.mac",
either by getmacros() or macroread(),

  Cmd> cov <- covar(x)

will read covar() and then execute it.  However, both macroread() and
getmacros() normally echo the header lines on macros; these often
contain details about usage which you otherwise might miss.

See below for discussion of keywords 'quiet', 'echo', 'silent',
'notfoundok' and 'nofileok'.

@@@@OUTOFLINE_on_header#OUTOFLINE on header
If 'OUTOFLINE' or simply 'OUT' appears on the first header line of the
macro, it will be marked to be always expanded out-of-line.  Otherwise,
the expansion of the macro will be determined by the value of option
'inline'.  See topics 'macros', 'options'.

@@@@reading_from_console_or_batch_file#Reading from console or batch file
macroread(CONSOLE [,prompt:F]) reads from the regular input stream
allowing you to type in the macro using the format described under topic
'macro_files'.

On windowed versions, 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 must be of the form 'Name
nLines MACRO', where nLines is the number of lines in the macro.

On any machine, when macroread(CONSOLE) is used in a batch file, it
reads the macro from the lines immediately following the macroread()
command.  See batch().  No prompt is printed when prompt:F is an
argument.

Any blank lines at the end of a macro are trimmed off when it is read.

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

  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           Lines of the macro itself 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 macro 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, header lines are printed when FileName is CONSOLE
and the macroread() command is in a batch file.  (In windowed versions,
a macro 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 macro is not found or
nofileok:T is an argument and the file cannot be opend, macroread()
returns NULL as value.  When used in a macro, this feature allows
special action to be taken if macroName is not found.  See topic 'NULL'.

@@@@file_and_string_keywords#Keywords 'file' and 'string'
macroread(file:FileName,...) is equivalent to macroread(FileName,...).

macroread(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 number of lines.  In
particular, mymacro <- macroread(string:CLIPBOARD) would read the first
macro on a replica of a data file in the special variable CLIPBOARD.  In
windowed versions this would be taken from the Clipboard.  In the GTK
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> macroread(quiet:T,"mymacro",file:"myfile.dat")
is equivalent to
  Cmd> macroread("myfile.dat","mymacro", quiet:T).

@@@@MACROFILES_variable#Variable MACROFILES
A predefined CHARACTER variable MACROFILES contains the names of files
containing macros.  A pre-defined macro getmacros() allows easy
retrieval of macros from the files whose names are in MACROFILES.  At
startup, MACROFILES is initialized to vector("graphics.mac",
"regress.mac", "design.mac", "tser.mac", "arima.mac", "mulvar.mac",
"math.mac", "macanova.mac"), but you can change it if desired.  See
topics getmacros() and addmacrofile().

@@@@see_also#Cross references
See also topics 'macros', macro(), read(), matread(), inforead(),
'macro_files', 'files'
@@@@______

====macros#macros,control,syntax
%%%%
mymacro <- macro(charVar [, dollars:T])
mymacro <- macroread(fileName [,"mymacro"])
getmacros(macro1 [, macro2 ...]) (reads macro from one of files
  specified in MACROFILES)
macrowrite(fileName, mymacro)
%%%%
@@@@description#Description
A macro is a collection of commands grouped together to make it easy to
execute them all at once.  It is used (invoked) the same way as a
function, by typing its name followed by 0 or more arguments in
parentheses.  For example, y <- boxcox(x,.5) invokes macro boxcox().

A macro is stored in the MacAnova workspace as a variable similar to a
CHARACTER scalar.  You can print its text by typing its name.

@@@@inline_macro_expansion
                      In-line expansion of a macro
By default, when a macro is invoked it is expanded in-line, that is, its
arguments are literally substituted into the text of the macro and the
modified text is inserted in the line being executed exactly as if it
had been typed in place of the macro call.

Because an in-line macro is inserted directly in the line, a particular
instance of a macro is expanded only once, even if it is repeatedly
encountered during a loop (see 'for' and 'while').  This makes it
impossible to redefine an in-line macro in a loop and execute the new
version the next time through.  However, a macro that is expanded
out-of-line (see below) is expanded every time it is encountered,
allowing meaningful redefinition within a loop.

@@@@defining_macros
                       Ways macros may be defined
Macros may be read from a file by macroread() or created directly using
macro().  There also many pre-defined macros such as readcols() and
boxcox().  Macros may be written to a file by macrowrite().

When you try to use a macro that has not been defined, the default
behavior of MacAnova is to print a warning message and then search the
standard macro files (specifically the files whose names are in
CHARACTER variable MACROFILES; see getmacros()) for the macro.  If the
macro is found, it is read in (without echoing the header lines) and
executed; if not, further execution of the command line is terminated.
Option 'findmacros' allows you to suppress the automatic search and/or
the printing of warning messages.  See topic 'options'.

A macro can be a component of a structure (see 'structures') although it
must be extracted in order to be used.  For example, if structure
boxcoxstr was created by boxcoxstr <- structure(boxcox),
boxcoxstr$boxcox(x,.5) is illegal.  You would have to use something like
@tmpboxcox <- boxcoxstr$boxcox;@tmpboxcox(x,.5).

@@@@out_of_line_macro_expansion
                    Out-of-line expansion of a macro
An alternative mode of macro expansion is out-of-line.  In this mode, a
modified copy of the macro text is created, substituting macro arguments
in the text.  This is then executed without being inserted in the line
being executed.  In a loop, a particular instance of an out-of-line
macro will be expanded every time through the loop.  The value of option
'inline' (default value is True) determines the default expansion mode.
In addition a macro can be marked always to be expanded out-of-line by
keyword phrase inline:F on macro().  See topics 'options' and macro().

@@@@see_also#Cross references
See also topics addmacrofile(), getmacros(), macro(), macrowrite(),
macrousage(), 'macro_files', 'macro_syntax'.

See macroread() for examples of macros.
@@@@______

====macrousage()#macros,general
%%%%
macrousage(Macro1 [,Macro2, ...] [,silent:T]), Macro1, Macro2, ...,
  currently defined macros
%%%%
@@@@usage#Usage
macrousage(Macro) prints all comment lines (lines that start with "#")
in Macro().  It is an error if Macro is not the name of a macro.  These
usally describe the usage of the macro, but that may not always be the
case.

macrousage(Macro, silent:T) does the same, except any warning messages
are suppressed.  silent:T does *not* suppress printing the usage
information.

macrousage(macroNames [,silent:T]), where macroNames is a quoted string
or CHARACTER variable specifying one or more macro names, prints the
comment lines in each macro named.

macrousage(arg1, arg2, ... [, silent:T]), where each argument is either
a macro or a CHARACTER variable does the same for several macros.

macrousage() returns in invisible LOGICAL scalar whose value is True if
and only if at least on macro was found.

@@@@examples#Examples
Example:
  Cmd> macrousage(colplot, rowplot)
  Cmd> macrousage(listbrief(macros:T, keep:T)) # usage for all macros
  Cmd> if (!macrousage(foo,silent:T)){print("foo not found")}

@@@@see_also#Cross references
See also topics help(), macro(), 'macros'.
@@@@______

====macrowrite()#macros,files,output
%%%%
macrowrite(fileName,a,b,... [,name:Name,header:F,comments:charVec,\
  oldstyle:T,stripdols:T]), a, b, ... macros, fileName and Name
  CHARACTER scalars, charVec a CHARACTER vector or scalar
%%%%
@@@@usage#Usage
macrowrite(FileName,a, b, ... ) writes macros a, b, ... on the file.
Filename must be a CHARACTER variable or quoted string and a, b,
... must be macros.  a, b, ... are written in the form recognized by
macroread.  The default is to write each with no line count in the
header and with a trailing line of the form %macroname%.

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.

If the macro was previously marked to be expanded out-of-line,
"OUTOFLINE" is added to the header line,

@@@@new_keyword#Keyword 'new'
Keyword 'new':
macrowrite(FileName, a, b, ..., new:T) removes all information currently
in the file before writing new information.  Without 'new:T', macros are
written at the end of the file.

@@@@comment_keyword#Keyword 'comment'
Keyword 'comment':
macrowrite(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.

@@@@header_keyword#Keyword 'header'
Keyword 'header':
macrowrite(FileName,a,b,...,header:F) writes the macros without any
header lines or any trailing %macroname%.  They will not be readable by
macroread().  Also, keyword 'comments' will be ignored.

@@@@oldstyle_keyword#Keyword 'oldstyle'
Keyword 'oldstyle'
macrowrite(FileName, a, b, ..., oldstyle:T) writes each macro in the old
style format.  A line count will be included in the header line and no
trailing %macroname% line will be written.

@@@@stripdols_keyword#Keyword 'stripdols'
Keyword 'stripdols'
macrowrite(FileName, a, b, ..., stripdols:T) strips '$$' off the end of
variable names of the form @name$$ as each macro is written, and adds
'DOLLARS' to the header line.  When the macro is subsequently read from
the file by macroread(), '$$' will be automatically added to all
temporary variable names of the form @name.  As long a macro originally
had no temporary variables that did not end in '$$', reading the macro
restores it exactly.  See topics 'macro_files' and 'variables'.  This
feature was added because it is easier to read and edit macros if the
temporary names don't all end in '$$'.

@@@@see_also#Cross references
See also topics getmacros(), 'macros', macro(), macroread(), matwrite(),
read(), matread(), 'macro_files', 'files'.
@@@@______

====makecols()#combining variables
%%%%
makecols(x,var1,var2, ... [,keyword phrases]), where x is a REAL matrix,
  var1, var2, ...  unquoted or quoted variable names
makecols(x,vector("var1","var2", ... ) [,keyword phrases])
makecols(x [,keyword phrases]), x a REAL matrix with labels.
makecols(charx,var1,var2, ... [,keyword phrases]), charx a CHARACTER
  scalar or vector
makecols(charx,vector("var1","var2", ... ) [,keyword phrases])
makecols(charx [,keyword phrases]), first line of charx containing
  variable names
Keyword phrases are factors:facVec, nomissing:T, quiet:T or silent:T,
  facVec a LOGICAL vector or vector of positive integers
%%%%
@@@@usage#Usage
makecols(x,name_1,...,name_k), where x is a REAL matrix and name_1, ...,
name_k are unquoted or quoted variable names, creates new REAL vectors
name_1, name_2, ... from the columns of x.

You can think of makecols() as a sort of inverse to hconcat().  If a
name which is not a quoted string is the name of an existing variable,
only the name is used, not the value of variable.  A report is printed
of the variables created.

It's OK for the number of names to differ from the number of columns in
x.  When there are more names than columns, the extras are ignored.
When there are more columns than names, the final columns are ignored.

makecols(x,vector("name_1","name_2",...,"name_k") [keyword phrases]) is
an alternative usage.

@@@@factors_keyword#Keyword 'factors'
makecols(x,name_1,...,name_k, factors:facVec) does the same, but
specifies that some of the columns of x are to be saved as factors.
facVec can be a vector of positive integer column numbers or a LOGICAL
vector of length k.  When facVec contains integers, they are the columns
of x to be saved as factors.  When facVec is LOGICAL, column i of x is
saved as a factor only if facVec[i] is True.  For example, when x has 4
columns, both makecols(x,a,b,c,y,factor:run(3)) and makecols(x,a,b,c,y,
factor:vector(T,T,T,F) saves columns 1, 2 and 3 of x as factors a, b and
c and column 4 of x as REAL vector y.

You can use keyword 'factors' with any other keyword.

@@@@character_argument_1#CHARACTER argument 1
makecols(charx,name_1,...,name_k), where charx is a CHARACTER scalar or
vector does the same, except the data to be saved is obtained as
vecread(string:charx, fields:T) (see subtopic vecread:"reading_from_
character_variable").

makecols(charx) does the same, provided the first line of CHARACTER
scalar or vector charx consists of a list of legal MacAnova names.

@@@@use_with_data_on_clipboard#Use with data on clipboard
An important special case of a CHARACTER first argument is
makecols(CLIPBOARD, name_1, ... [,factors:TorFvec).  You could use this
when you have copied a data matrix to the clipboard, perhaps in a spread
sheet program.  makecols(CLIPBOARD [,factors:TorFvec[) would be
appropriate when the first line of the selection copied contained column
headings to be used as variable names.  See topic 'CLIPBOARD'.

@@@@quiet_and_silent_keyword#Keywords 'quiet' and' 'silent'
makecols(x,name_1,...,name_k,quiet:T) does the same, except no report is
printed.

makecols(x,name_1,...,name_k,silent:T) does the same, except nothing is
printed, not even warning messages.

'quiet:T' and 'silent:T' can always be used, no matter how names are
specified.

@@@@nomissing_keyword#Keyword 'nomissing'
makecols(x,name_1,...,name_k,nomissing:T) does the same except any
MISSING values are removed from the variables created.  If all the
elements in a column of x are MISSING, the corresponding variable is
NULL.  A warning message is printed unless 'silent:T' is an argument.

'nomissing:T' can always be used, no matter how names are specified.

@@@@names_from_column_labels#Names from column labels
makecols(x), with no names provided, is legal when x has labels.  It is
equivalent to makecols(x,getlabels(x2)), and creates variables using the
column labels as names.  See topics 'labels', getlabels().

The first argument can also be a CHARACTER scalar or vector such as
CLIPBOARD; see below.

@@@@examples#Examples
Example:
  Cmd> makecols(x, x1, x2, x3, x4)
  Cmd> makecols(x,"x1","x2","x3","x4")
  Cmd> makecols(x, vector("x1","x2","x3","x4"), quiet:T)

These all create vectors x1, x2, x3 and x4 from the first 4 columns of
x.  All but the last print a report that these vectors were created

  Cmd> makecols(x, x1, x2, x3, x4, nomissing:T,silent:T)

This does the same except x1, ..., x4 will have no MISSING values, with
no report and any warning messages suppressed.

  Cmd> makecols(data,a,b,c,y,factors:run(3))

  Cmd> makecols(data,a,b,c,y,factors:vector(T,T,T,F)

These both save columns 1, 2 and 3 of data as factors a, b and c and
column 4 as vector y.

  Cmd> makecols(vector("1 2","3 4"),x,y)# makecols(" 1 2\n 3 4", x, y)
  Cmd> makecols(vector("x y","1 2","3 4"))# makecols("x y\n 1 2\n 3 4")

These both create vectors x and y of length 2 by "reading" the CHARACTER
first argument.
@@@@______

makecols() is implemented as a pre-defined macro.

@@@@see_also#Cross references
See also topics readcols(), clipreaddata(), hconcat().
@@@@______

====makefactor()#glm,anova,character variables
%%%%
makefactor(vec [,sort:F] [,labels:T or F]), vec a REAL, CHARACTER or
  LOGICAL vector
%%%%
@@@@usage#Usage
makefactor(vec) creates a factor constructed from the REAL, CHARACTER or
LOGICAL vector vec.  If there are m unique values in vec, the output
will be a factor with m levels in the same order as the values in vec.
MISSING values remain MISSING.

makefactor(vec, sort:F) does the same, except the factor levels may not
have the same order as the elements of vec.  Level 1 will be assigned to
value[1], level 2 to the next value in vec different from vec[1], and so
on.

If vec is a CHARACTER vector without row labels, its values are attached
to the result as row labels unless 'labels:F' is an additional argument.

@@@@with_labeled_argument#With labeled argument
If vec has row labels, they become the row labels of the result.

makefactor(vec, labels:F, [, sort:F]) does the same, except the result
has no row labels.

makefactor(vec, labels:T, [, sort:F]) does the same, except that if vec
does not have labels, a CHARACTER representation of the values in vec is
attached to the result as row labels.

@@@@makefactor_vs_factor#makefactor() vs factor()
Even when vec is REAL and consists of positive integers, it may be
preferable to use makefactor() rather than factor(), since the output
from factor() will not contain all m levels if max(vec) > m, or if some
levels are missing in vec.

@@@@examples#Examples
Examples:
  Cmd> a <- makefactor(vector(5.2,2.6,3.9,1.3,3.9,1.3,5.2,2.6)); a
  (1)           4           2           3           1           3
  (6)           1           4           2

  Cmd> b <- makefactor(vector("D","B","C","A","C","A","D","B"));b
           D           B           C           A           C
           A           D           B
           4           2           3           1           3
           1           4           2

  Cmd> c <- makefactor(vector(5.2,2.6,3.9,1.3,3.9,1.3,5.2,2.6),sort:F);c
  (1)            1            2            3            4            3
  (6)            4            1            2

  Cmd> d <- makefactor(rpoi(5,11)/10,labels:T); d
           1.2         0.9           1         1.4         0.9
             3           1           2           4           1

makefactor() is implemented as a macro.

@@@@see_also#Cross references
See also factor().
@@@@______

====makestr()#structures,combining variables
%%%%
makestr(var1 [,var2,...,vark] [, KeyPhrases]), where var1, var2, ... are
  arbitrary variables
KeyPhrases can be compnames:Charvec, labels:lab, and silent:T, where
  Charvec and lab are CHARACTER scalars or vectors.
Use structure() instead.
%%%%
@@@@usage#Usage
makestr() is identical to structure().  See structure() information
on its use.

The use of makestr() is deprecated -- that is, it will continue to be
available for the immediate future, but at some point may be disabled.
Use structure() instead.

@@@@see_also#Cross references
See also topics strconcat(), 'structures', 'keywords', changestr(),
compnames().
@@@@______

====makesymbols()#character variables,plotting
%%%%
plotsymbols(intVar), intVar a REAL variable with integer elements
  between 1 and 255
plotsymbols(charVar [,medium:T or small:T]), charVar a CHARACTER
  variable of shape names "diamond", "plus", "square", "cross",
  "triangle", "star", "dot" or "circle"
%%%%
@@@@usage#Usage
makesymbols(intVar), where intVar is a REAL scalar, vector, matrix or
array whose elements are integers between 1 and 255 returns a CHARACTER
variable with the same size and shape as intVar.  Each element of intVar
is interpreted as an ASCII code and the corresponding element of the
result is the single character with that code.

  Cmd> symbols <- makesymbols(vector(2,29,65,97)); symbols
  (1) "\002"            [octal representation of 2]
  (2) "\035"            [octal representation of 29]
  (3) "A"               [ASCII code 65]
  (4) "a"               [ASCII code 97]

makesymbols(charVar), where charVar is a CHARACTER scalar, vector,
matrix or array, also returns a CHARACTER variable the same size and
shape as charVar.  Any element of charVar whose first three characters
match the first three letters of "diamond", "plus", "square", "cross",
"triangle", "star", "dot" or "circle", is replaced in the result by
"\001", "\002", "\003", "\004", "\005", "\006", "\007", or "\010",
respectively.  These are the plotting symbol codes for these shapes.
Any elements of charVar not specifying one of these shapes are put in
the result without change.

  Cmd> makesymbols(vector("diamond","dot","circle"))
  (1) "\001"
  (2) "\007"
  (3) "\010"

symbols <- makesymbols(charVar, medium:T) does the same except the shape
names are translated to "\011", "\012", "\013", "\014", "\015",
"\016", "\017", or "\020".

symbols <- makesymbols(charVar, small:T) does the same except the shape
names are translated to "\021", "\022", "\023", "\024", "\025",
"\026", "\027", or "\023".

See subtopic "chplot:drawn_plotting_symbols" for more information about
plotting symbols.  In particular, in specifying these symbols
explicitly, leading 0's can be omitted, so chplot(x,y,symbols:"\7") is
the same as chplot(x,y,symbols:"\007").

@@@@use_in_plotting#Use in plotting
makesymbols() is designed to be used to create a CHARACTER vector or
matrix to be used as the value of keyword 'symbols' on plotting commands
such as plot(), chplot() and addchars().  For this usage the dimensions
of intVec and charVec must match what is expected.  See subtopic
"chplot:symbol_variable_shape" for details.

Examples:
In the following, x is a vector and y a matrix with 3 columns:

  Cmd> plot(x,y[,1],symbols:makesymbols("diamond"))#or makesymbols(1)

plots column 1 of y using diamonds (code "\001") as plotting symbol.

  Cmd> lineplot(x,y, symbols:makesymbols(vector("dia","plus","squ"),\
       medium:T))

  Cmd> lineplot(x,y, symbols:makesymbols(9, 10, 11))

  Cmd> lineplot(x,y, symbols:vector("\11", "\12", "\13"))

all make line plots of the columns of y, with medium sized diamonds,
plus signs and squares used as plotting symbols for each columns

@@@@difference_from_putascii#Difference from putascii()
When intVar is a vector, the usage makesymbols(intVar) is somewhat
similar to putascii(intVar, keep:T) since both translate ASCII codes to
characters.  The difference is that putascii() returns a CHARACTER
scalar with length(intVar) characters while makesymbols() returns a
CHARACTER vector of length(intVar), with each element a single
character.

@@@@see_also#Cross references
See also topics chplot(), 'plotting', putascii().
@@@@____

====manova()#glm,multivariate analysis,anova
%%%%
manova([Model] [,print:F or silent:T, coefs:F, pvals:T, fstats:T,\
  byvar:T, sssp:F or T]), Model a CHARACTER scalar
%%%%
@@@@usage#Usage
manova(Model) computes a MANOVA table of SS/SP (sums of squares and sums
of products) matrices for the model in the CHARACTER variable Model.
The response variable should be a matrix with rows as cases and columns
the variables.

Type 'help(models)' for information on how to specify Model.

If the response is univariate (has only one column), manova() is
equivalent to anova().

Unless 'marginal:T' is an argument, SS/SP matrices are computed
sequentially (so called SAS Type I quantities).

Normally, when each row of a SS/SP matrix will fit on a single line, all
matrices are printed in their entirety.  When a row would require more
than one line, only the term names and the degrees of freedom are
printed.  This behavior can be modified by keywords 'sssp', 'byvar',
'fstats' and 'pvals'; see below.  In any case the matrices are saved in
the three-dimensional side effect array SS, with the first subscript
indexing terms and with the first dimension labeled by TERMNAMES.

@@@@weights_keyword#Keyword 'weights'
manova(Model,weights:Wts) does a weighted analysis.  Wts must be a REAL
vector with Wts[i] >= 0 and nrows(Wts) = nrows(response).  The results
are the same as if the i-th row of the response and all X-variables
(variates and dummy variables and their products), including the
constant vector were multiplied by sqrt(Wts[i]) and a least squares fit
(without an intercept) computed.  You can abbreviate 'weights:Wts' to
'wts:Wts'.

@@@@no_model_supplied#No model supplied
manova() or manova(,weights:Wts) (no model supplied) uses the model used
by the most recent GLM command such as manova(), anova(), or poisson().
See topic 'glm'.

@@@@side_effect_variables_created#Side effect variables created
Side effect variables created are RESIDUALS, HII, DF, SS, DEPVNAME,
TERMNAMES, and STRMODEL.  When weights are specified, RESIDUALS =
Response - Fitted and WTDRESIDUALS = sqrt(Wts)*RESIDUALS is an
additional side effect vector.  You should use WTDRESIDUALS rather than
RESIDUALS in residual plots or other diagnostic procedures.

@@@@multivariate_tests#Multivariate tests
SS is a 3-dimensional array such that SS[j,,] is the sum of squares and
products matrix for term j.  If the appropriate error matrix for the
k-th term is SS[j,,], the eigenvalues needed for several standard tests
(Wilks, Roy, Pillai, Hotelling generalized T-squared) may be computed by
releigenvals(SS[j,,],SS[k,,]) or you can compute some test statistics
directly, for example,
  Cmd> T2 <- dferror*trace(solve(SS[k,,],SS[j,,])
or
  Cmd> lambda <- det(SS[j,,])/det(SS[k,,]+SS[j,,]).

@@@@keywords
                             Other Keywords
Keyword phrase  Default  Meaning
  byvar:T          F     Computes a complete ANOVA table for each
                         variable.  The full SS/SP matrices are not
                         printed although they are still available in
                         array SS.

  sssp:T         none    Forces the printing of the full SS/SP matrices,
                         even when each row would require more than one
                         line.  This option is ignored with any of
                         fstats:T, pvals:T, or byvar:T.
  sssp:F                 Suppresses printing of the full SS/SP matrices,
                         even if a row would fit on a single line.  Only
                         the term names and degrees of freedom are
                         printed.

See topic 'glm_keys' for information on keyword phrases 'print:F',
'silent:T', 'fstats:T', 'pvals:T', 'coefs:F' and 'marginal:T'.

@@@@byvar_keyword#Keyword 'byvar'
When byvar:T is an argument, options (not keywords) 'fstats' and 'pvals'
have the same effect as with anova().  If byvar:T is not an argument,
these options are ignored.  See topics 'options' and 'glm_keys'.

When byvar:T is not an argument, options 'fstats' and 'pvals' are
ignored.  If either 'fstats:T' or 'pvals:T' is an argument, univariate
SS and MS are printed for each variable and term, together with F-
statistics and/or P values .  The information is essentially the same as
with byvar:T except that all the statistics for a term are grouped
together.  The full SS/SP matrices are not printed but are available in
array SS.

@@@@interaction_with_other_functions#Interaction with other functions
contrast(), coefs(), predtable(), and cellstats() work after manova().
@@@@______

====match()#ordering,variables,character variables
%%%%
match(x,Target [,nomatch, exact:F or fuzz:d, relative:T, ignorecase:T]),
  x REAL, LOGICAL or CHARACTER, Target a variable of the same type as x,
  nomatch and d >= 0 REAL scalars; x and Target can't both be nonvectors
%%%%
@@@@usage#Usage
match(x,Target,noMatch), where x is REAL, LOGICAL or CHARACTER and
noMatch is a REAL scalar, attempts to match each element of array x with
each element of vector Target.  Target must be the same type as x.  The
result is REAL with the same dimensions as x.  When x is REAL or
LOGICAL, it is an error for Target to contain any MISSING values.

Let J represent the subscripts of an element of x.  Then result[J] has
value noMatch, when no element of Target matches x[J], and has value k
when Target[k] is the first value with Target[k] = x[J].  When x is REAL
and x[J] is MISSING, then result[J] is MISSING.

match(x,Target) does the same except that length(Target) + 1 is used as
a value for noMatch and, when there are any non-matching elements, an
advisory message is printed.

When x is a vector, Target can be a matrix or array and the matching is
done for each combination of the second and higher dimension of Target.
The result has dimensions vector(length(x), dims(Target)[-1]).  In this
case, when noMatch is omitted, the value for non-matching elements is
dim(Target)[1] + 1.

@inexact_matching
match(x,Target [,noMatch], fuzz:d), where x is REAL and d >= 0 is a
non-MISSING REAL scalar, does the same, except that x[J] matches
Target[k] when abs(x[J] - Target[k]) <= d.

match(x,Target [,noMatch], fuzz:d, relative:T) does the same, except
that x[J] matches Target[k] when (abs(x[J] - Target[k]) <= D, where
D = d*(abs(x[J]) + abs(Target[k])).

match(x,Target [,noMatch], ignorecase:T) ignores the case, upper or
lower, of any alphabetic characters in elements of CHARACTER variables x
and A.  For example, match("AbC",vector("xYz","abc","def"),
ignorecase:T) has value 2.

match(Pattern,Target [,noMatch], exact:F [,ignorecase:T]), where Pattern
is a CHARACTER scalar containing one or more of the "wild card"
characters '*' and '?', and Target is a CHARACTER vector, does the same,
except that an exact match is not required to 'hit' Target.

@@@@wild_card_characters
                    Wild card characters '*' and '?'
A '*' in Pattern will match 0 or more successive characters of an
element of Target, without regard to what they are.  A '?' in Pattern
will match any single character of an element of Target, without regard
to what it is.  For example, "start*" matches the first element of
Target that begins with "start", "*mid*" matches the first element
containing "mid", "*mid1*mid2*end" matches the first element finishing
with "end" that earlier contains "mid1" and "mid2" in that order, "p?l*"
matches the first element starting with 'p' and whose third letter is
'l', and so on.  As particular cases, "*" always matches Target[1] and
"\"*\"" matches the first element starting and ending with '"'.

@@@@examples#Examples
Examples:
  match(vector(1.3,2.4,1.3,5,5.1),vector(2.4,1.3),-1) returns
    vector(2,1,2,-1,-1)
  match(vector(1.3,2.4,1.3,5,2.4,?),vector(2.4,1.3)) returns
    vector(2,1,2,3,1,?)
  match(vector(1.3,2.4,1.3,5,2.4),run(3),-99,fuzz:.5) returns
    vector(1,2,1,-99,2)
  match(vector("A","B","A","C","B"),vector("B","A")) yields
    vector(2,1,2,3,1)
  a <- factor(match(x,sort(unique(x)))) transforms a REAL x to a factor
  unique(x)[match(x,unique(x))] yields x when x is a vector.
  match(scalarValue,vec,0) != 0 if and only scalarValue is in vec
  match("*c",vector("abc","ade","gfh"),exact:F) returns 1
  match("*d*",vector("abc","ade","gfh"),exact:F) returns 2
  match("g*",vector("abc","ade","gfh"),exact:F) returns 3
  match("g*h",vector("abc","ade","gfh"),exact:F) returns 3
  match("a*b*c",vector("abc","ade","gfh"),exact:F) returns 1
  match("a*b???",vector("aqbde","bb123", "allbdef"),exact:F) returns 3

In a macro, it can be helpful to know whether an argument is a an
explicit quoted string:
  if (match("\"*\"","$1",0,exact:F) != 0){
    print("arg 1 is a quoted string")
  }

@@@@see_also#Cross references
See also unique(), 'macro_syntax'.
@@@@______

====mathhelp()#general,matrix algebra
%%%%
mathhelp(topic1 [, topic2 ...] [,usage:T] [,scrollback:T])
mathhelp(topic, subtopic:Subtopics), CHARACTER scalar or vector
  Subtopics
mathhelp(topic1:Subtopics1 [,topic2:Subtopics2 ...])
mathhelp(key:Key), CHARACTER scalar Key
mathhelp(index:T [,scrollback:T])
%%%%
@@@@usage#Usage
mathhelp(Topic1 [, Topic2, ...]) prints help on topics Topic1, Topic2,
... related to macros in file math.mac.  The help is taken from file
math.mac.

mathhelp(Topic1 [, Topic2, ...] , usage:T) prints usage information
related to these macros.

mathhelp(index:T) or simply mathhelp() prints an index of the topics
available using mathhelp().  Alternatively, help(index:"math") does the
same thing.

mathhelp(Topic, subtopic:Subtopic), where Subtopic is a CHARACTER scalar
or vector, prints subtopics of topic Topic.  With subtopic:"?", a list
of subtopics is printed.

mathhelp(Topic1:Subtopics1 [,Topic2:Subtopics2], ...), where Suptopics1
and Subtopics2 are CHARACTER scalars or vectors, prints the specified
subtopics.  You can't use any other keywords with this usage.

In all the first 4 of these usages, you can also include help() keyword
phrase 'scrollback:T' as an argument to mathhelp().  In windowed
versions, this directs the output/command window will be automatically
scrolled back to the start of the help output.

@@@@key_keyword#Keyword 'key'
mathhelp(key:key) where key is a quoted string or CHARACTER scalar lists
all topics cross referenced under Key.  mathhelp(key:"?") prints a list
of available cross reference keys for topics in the file.
@@@@______

mathhelp() is implemented as a predefined macro.

@@@@see_also#Cross references
See help() for information on direct use of help() to retrieve
information from math.mac.
@@@@______

====matprint()#output,files,missing values
%%%%
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.
%%%%
@@@@usage#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.

@@@@width_keyword#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#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#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#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.

@@@@name_keyword#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.

@@@@comment_keyword#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.

@@@@missing_keyword#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.

@@@@header_keyword#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.

@@@@width_keyword#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.

@@@@sep_keyword#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.

@@@@quoted_and_bylines_keywords#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:",").

@@@@empty_file_name#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.

@@@@nsig_and_format_keywords#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#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#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#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'.

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

====matread()#input,files,missing values
%%%%
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.
%%%%
@@@@usage#Usage
In the following you can substitute read() for matread().  The only
difference between them is that read() prints no warning message when it
finds a macro rather than a data set.

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)

If setName is the name of a macro rather than a data set, it will be
read, but a warning message is printed (no warning printed by read()).

@@@@empty_file_name#Empty file name
In a version with windows, if FileName is the null string "", you will
be able to select the file using a dialog box.

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

@@@@macro_getdata#Macro getdata()
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 getdata() to read data sets from your file.  See
topic getdata().

@@@@too_large_data_items#Too large data items
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.

@@@@unreadable_items#Unreadable items
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.

@@@@reading_from_console_or_batch_file#Reading from CONSOLE or batch file
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 windowed versions, type one line at a time in the
dialog box that is opened.  On nonwindowed versions, 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.

@@@@keywords#Keywords
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'.

@@@@notfoundok_keyword#Keyword 'notfoundok'
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.

@@@@file_and_string_keywords#Keywords 'file' and 'string'
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 a version with windows, this would be taken from
the Clipboard.  In the GTK 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#Cross references
See also topics read(), vecread(), readcols(), macroread(), inforead(),
'files'.
@@@@______

====matread_file%#variables,files,input,output
%%%%
Type 'help(matread_file)' for information on the format of files
to be read by matread() and read().
%%%%
@@@@introduction#Introduction
This topic discusses the format of files to be read by matread() and
read().  They are plain text files which contain named data sets, each
starting with one or more header lines, such as are written by
matprint() and matwrite().

matread() and read() behave identically except that read() does not
print a warning message when the name requested belongs to a macro
rather than a data set.  In the following, you can substitute 'read()'
for 'matread()'.

No more than 50 numerical items can be on any single line of a data set
read by matread() or read().

@@@@general_description_of_format#General description of format
A single file can contain one or more named data sets corresponding to
any type of variable except GRAPH.  This includes REAL, LOGICAL and
CHARACTER data, as well as NULL variables, macros and structures.  Data
sets can have coordinate labels and/or descriptive notes.  See topics
'variables', 'logic', 'NULL', 'notes'.  The file can also have macros
readable by macroread() mixed in among the data sets.  See topics
'macro_files' and macroread().

Every data set must have one or more header lines which give the data
set name, information about its structure and internal format.  The
first line starts with the name and is called the 'name line'.
read(fileName, setName) and matread(fileName, setName) search the file
for the first line which starts with 'setName'.  Such a line is assumed
to be the name line for the data set.

@@@@ENDED_header_keyword#'ENDED' header keyword
Any data set may optionally be followed by a line starting '%setName%',
where 'setName' is its name.  When this is done, keyword 'ENDED' should
appear on the name line of the data set.  When the data sets has
associated labels or notes, '%setName%' should follow them.  This usage
allows read() and matread() to skip past a data set without examining
individual lines.  Even if a line in such a data set starts with the
name of another data set, read() and matread() will not "see" it and
mistakenly treat it as a name line.

@@@@end_of_macros_line#End of macros line
A line starting _E_N_D_O_F_M_A_C_R_O_S_ terminates a search for a data
set or a macro.  You can put help or other information after this line
without the danger that a line might be mistaken for the start of a data
set.

@@@@format_of_header
                       Format of data set header
The first header line for each data set starts with its name, followed
by dimension information and possibly keywords.  This line may be
optionally followed by descriptive comment lines starting with ')'.
These may also provide information on the number of values per line and
coding for MISSING values.  Thus a data set starts with the following
general form:
   Name Dims Keywords
   ) 0 or more descriptive or comment lines starting with ')', referred
   ) to as 'comment lines' below
   ) .....

@@@@data_set_name#Data set name
Name is the name of the data set ('mydata', say) to be matched to
setName, the second argument to read() or matread().  Case is ignored in
searching for the name, so that read(fileName, "mydata") will find
mydata, MyData, or MYDATA, for example.

@@@@data_dimensions#Data dimensions
Dims, the dimensions of the data set, is a list of 1 or more positive
integers.  When Dims is a single number ('mydata 20'), the data set is a
vector of length Dims or a structure with Dims components.  When it is
two numbers, nrows and ncols, ('mydata 20 5') the dataset is a nrows by
ncols matrix.  If Dims consists of p >= 3 numbers, the data set is a
p-dimensional array.

It is also acceptable for Dims to be '0', in which case no data is
expected.  When such a data set is read by read() or matread(), the
comment lines are printed and NULL is returned.  A useful convention is
to have the first "data set" on a file be empty, with the comments
describing the remainder of the file.  See topic 'NULL'.

@@@@header_line_keywords
        Keywords that may be put on the first line of the header
  Keyword                            Description
  CHARACTER           The data set is a CHARACTER variable in either "by
                      fields" or "by lines" format (see below)
  COLS or COLUMNS     The data follow in transposed form.  For a matrix,
                      this is in column by column order, each column
                      starting on a new line.
  ENDED               A line starting '%setName%', where 'setName' is
                      the name of the data set, immediately follows the
                      data set.  This does not affect how the data set
                      is read.
  FORMAT              Indicates that a Fortran format starting with '('
                      will follow the last comment line.  It is ignored
                      by MacAnova but might help a program written in
                      Fortran to read the data.
  LABELS              The data set has coordinate labels which follow
                      the data in the file (see below)
  LOCKED              If the result of matread(), macroread() or read()
                      is assigned to a variable, that variable will be
                      locked.  See topic 'locks'.
  LOGICAL             The data set is a LOGICAL variable, with False and
                      True represented as zero and non-zero values,
                      respectively.  Most commonly these are 0 and 1.
  NOTES               The data set has attached descriptive notes which
                      follow the data in the file (see below).
  NULL                The data set is a NULL variable, containing no
                      data, although there may be comment lines.  Dims
                      must be 0.  There can be no other keywords.  See
                      topic 'NULL'.
  QUOTED              The data set is a CHARACTER variable in "by quoted
                      fields" format (see below).
  REAL                The data is a REAL variable.  This is the default
                      and hence REAL is never required
  ROWS                The data follow a row at a time (constant value
                      for first subscript), each row starting on a new
                      line.  This is the default and hence ROWS is never
                      required.
  STRUCTURE           The data set is a structure.

Upper and lower case letters are not distinguished in these keywords,
so, for example, 'macro' and 'Macro' are both recognized as the same as
'MACRO'.

@@@@vector_treated_like_matrix#Vector treated like matrix
A vector (single dimension specified) is treated like a matrix with a
single column.  That is, if COLS or COLUMNS is specified it should all
be on one line, and if not, every element must be on a separate line.

@@@@comment_line_conventions
                      Conventions on Comment lines
  ) LOGICAL      The data are to be interpreted as being LOGICAL, with
                 zero and non-zero values translated to F and T,
                 respectively.  This is retained for backward
                 compatibility and is ignored for CHARACTER, NULL or
                 STRUCTURE data sets.

  )"%f %f... %f" specifies a format for each row of a REAL or LOGICAL
                 data set that is analogous to that used by scanf in the
                 C programming language.  If the data set is CHARACTER,
                 '%f' is replaced by '%s'; see below.  Let N1 and Nk be
                 the first and last dimensions.  If there are fewer
                 "%f"'s than Nk (or fewer than N1 if COLS or COLUMNS is
                 specified), then this indicates that, for each value of
                 the last index (first index with COLS or COLUMNS),
                 there are several lines in the file containing data.
                 Each such line, except possibly the last, must have the
                 same number of data items as there are %f's.  If no
                 explicit format is given, one with Nk or N1 (if COLS or
                 COLUMNS is on line 1 of the header) %f's is assumed.
                 No more than 50 values can be put on a single line.

  )"NNx%f %f ... %f" where NN is an integer, causes the first NN
                 characters of each line to be skipped.  This allows you
                 to skip case labels or line numbers.  Example: )"12x%f
                 %f" skips 12 characters at the start of each line.

  )"%s %s ... %s" specifies a format for each row of a CHARACTER data
                 set.  If present, the data will be expected to be in
                 "by fields" format or "by quoted fields" (if QUOTED is
                 on header line) format (see below).  The number of
                 "%s"'s is the maximum number of elements that will be
                 read per line.

  )"NNx%s %s ...%s" where NN is an integer causes the first NN
                 characters of each line read to be skipped before
                 scanning for CHARACTER data in "by fields" or "by
                 quoted fields" format.

  ) MISSING XX   where XX is a number indicates that XX in the data set
                 is to be read as MISSING.  The default missing value
                 code is -99999.9999.  Because only integers can be
                 guaranteed to be represented exactly in the computer,
                 it is preferable for XX to be an integer, positive or
                 negative.  Example: ) MISSING -99 specifies MISSING is
                 coded as -99.  This is ignored for data sets that are
                 not REAL or LOGICAL.  MISSING must be all upper case.

@@@@character_data_formats
                         CHARACTER data formats
There are three possible formats for CHARACTER data, 'by lines', 'by
fields' and 'by quoted fields'.  'Quoted' means enclosed in "'s as in
"Regression analysis".

 By lines
   Each element starts on a new line and is not quoted.  If an element
   extends over more than one line, each line except the last must end
   with '\'.  This format is signaled by the presence of CHARACTER on
   the header and the absence of any ")%s..."  format among the comment
   lines.

 By fields
   Each stretch of "non-white" characters on a line is considered to be
   an element.  This format is signaled by the presence of CHARACTER on
   the header and the presence of a ")%s..." format among the comment
   lines.  The number of fields on a line is the number of "%s"'s in the
   format.  Commas are treated as non-white characters and do not
   separate fields.

 By quoted fields
   Each element must be enclosed in quotes ("...") and elements in a
   line are separated by spaces, tabs, and possibly a comma.  This
   format is signaled by the presence of QUOTED on the header.  If there
   is no ")%s..." format among the comment lines, the number of items
   expected per line is the size of the last dimension or 1 if the data
   set is a vector.  If COLUMNS or COLS is on the header, the default
   number expected per line is the size of the first dimension.  If
   there is a ")%s..."  format, the number of elements expected per line
   is no more than the number of "%s"'s in the format, with any
   additional lines, except the last, having the same number of
   elements.

@@@@structure_format
                     Format for structure data sets
The name line for a structure data set must be of the form
   strName   ncomps  STRUCTURE
where strName is the name of the structure and integer ncomps > 0 is the
number of components.  There must follow ncomps data sets, each in one
of the formats just described, or in the format for a structure.  Each
component must have a name of the form strName$compName, where compName
is the name of the component.  If a component is a structure, then the
names of its components would thus be strName$compName$compName1.

Each structure component *must* be preceded by at least one blank line.
An individual component can be read like any other data set by
specifying its full name, "mystruc$b", for example.

@@@@labels_and_notes_format
                      Format for labels and notes
If a variable with name "x", say, has coordinate labels (see topic
'labels'), the header line must contain keyword "LABELS", and the labels
for all coordinates must be in a CHARACTER vector with name "x$LABELS"
immediately following the data associated with x.  When ndims(x) > 1,
the labels for the first dimension come first, followed by those for the
second dimension, and so on, all in one vector.  Thus the length of the
vector normally matches the sum of the dimensions of x.  Because they
are written in the usual form for a CHARACTER vector, you can read the
labels without reading the data by read(fileName, "x$LABELS").

Labels may be "expanded" similarly to the expansion done by setlabels().
Specifically, if the number of x$labels is less than the sum of
dimensions of x, any label starting with '@' or of the form '(', '[',
'{', '<', '/', or '\' is expanded to the length of the appropriate
dimension.  For example, labels vector("@[", "X1", "X2") for a 10 by 2
matrix are equivalent to vector(rep("@[",10), "X1","X2").  See topics
'labels', setlabels().

If variable x has attached notes (see topic 'notes'), the header line
must contain keyword "NOTES", and the notes must be in a CHARACTER
vector with name "x$NOTES" immediately following the data or labels.
Because notes are written in the usual form for a CHARACTER vector, you
can read them without reading the data by read(fileName, "x$NOTES").

@@@@example_data_file
                      Example data file, data.txt

  info           0
  ) Sample data file containing REAL data set sampledata,
  ) CHARACTER data set samplechars, and structure mystruct

  sampledata     4     3 COLUMNS LABELS NOTES ENDED
  ) Small REAL data set with one missing value coded as -99.
  ) Each line contains data for one column (COLUMNS on header)
  ) MISSING -99
  ) '4x' in the following format skips 4 characters (variable label)
  )"4x%f %f %f %f"
  Temp   34.5   45.2  23.1   20.1
  Conc   .170   -99  .883    .401
  Secs    3.5   4.7   3.2     5.8

  sampledata$LABELS    4   QUOTED COLUMNS
  ) Labels for sample data in quoted format by columns
  ) Labels are expanded to "@" "@" "@" "@" "Temp" "Conc" "Secs"
  )"%s %s %s %s"
   "@" "Temp" "Conc" "Secs"

  sampledata$NOTES     1 CHARACTER
  ) Notes for sampledata in "by line" format
  Small REAL data set with one missing value.
  %sampledata%

  samplechars    2     4 CHARACTER
  ) 4 by 2 CHARACTER matrix with each row in 2 lines containing
  ) 3 and 1 unquoted fields
  )"%s %s %s"
  This is by-fields
  format
  without any double
  quotes

  mystruc  2  STRUCTURE
  ) this is a structure with two components, a and b
  ) The blank line before the header of each component is required

  mystruc$a  2 QUOTED COLUMNS
  ) character vector of length 2
  ) Two quoted fields
  "The quick brown fox" "Jumps over the lazy dog"

  mystruc$b  2 STRUCTURE
  ) This component is a structure with two components, pi and e

  mystruc$b$pi  1   1
  ) 1 by 1 matrix
  3.14159265358979

  mystruc$b$e   1
  ) vector of length 1
  2.71828182845905

@@@@examples#Examples
              Examples of reading data sets from data.txt

  Cmd> sampledata <- read("data.txt","sampledata", quiet:T)

  Cmd> print(sampledata) # note that labels were read
  sampledata:
              Temp         Conc         Secs
  (1)         34.5         0.17          3.5
  (2)         45.2      MISSING          4.7
  (3)         23.1        0.883          3.2
  (4)         20.1        0.401          5.8

  Cmd> getnotes(sampledata) # notes were retrieved as well as data
  (1) "Small REAL data set with one missing value."

  Cmd> notes <- read("data.txt", "sampledata$notes"); notes
  (1) "Small REAL data set with one missing value."

  Cmd> samplechars <- read("data.txt","samplechars",quiet:T)

  Cmd> print(samplechars)
  samplechars:
  (1,1) "This"
  (1,2) "is"
  (1,3) "by-fields"
  (1,4) "format"
  (2,1) "without"
  (2,2) "any"
  (2,3) "double"
  (2,4) "quotes"

  Cmd> mystruc <- read("data.txt","mystruc",quiet:T)

  Cmd> print(mystruc)
  mystruc:
  component: a
  (1) "The quick brown fox"
  (2) "Jumps over the lazy dog"
  component: b
    component: pi
  (1,1)       3.1416
    component: e
  (1)       2.7183

  Cmd> mystruc_b <- read("data.txt", "mystruc$b",quiet:T)

  Cmd> print(mystruc_b)
  mystruc_b:
  component: pi
  (1,1)       3.1416
  component: e
  (1)       2.7183

In these examples, 'quiet:T' suppresses echoing the header line and
comments.  See read() and matread().

@@@@see_also#Cross references
See also topics read(), matread(), matprint(), matwrite(), 'files',
'macro_files'.
@@@@______

====matrices#matrix algebra,operations,variables
%%%%
Matrix transposition       x' or t(x)
Matrix multiplication      x %*% y, x %c% y, x %C% y
Matrix inversion           solve(a)
Linear equation solution   solve(a, b) or a %\% b, rsolve(a,b) or
                           b %/% a
Extract elements           x[i,j], x[,j], x[i,], i, j integer scalars or
                           vectors or LOGICAL vectors.
Eigen values and vectors   eigen(a), eigenvals(a), releigen(a,b),
                           releigenvals(a,b), trideigen(diag,subdiag...)
Other decompositions       qr(x [,pivot:T]), cholesky(x),
                           svd(x [all:T, right:T or F, left:T or F])
Other Functions of matrices
                           trace(x), det(x), diag(x), nrows(x), ncols(x)
Create matrices            matrix(x,nrows), hconcat(a,b,...),
                           vconcat(a,b,...), dmat(vec), dmat(x, n)
%%%%
@@@@description#Description
A matrix is a two dimensional array, that is, it has two subscripts.

If x is a REAL, LOGICAL, or CHARACTER vector of length m*n, matrix(x,m)
creates an m by n matrix from the elements of x.

A vector of length n is, in most contexts, equivalent to a n by 1
matrix.  See topic 'vectors'.

@@@@generalized_matrix#Generalized matrix
A generalized matrix is an array with more than two dimensions but which
has no more than 2 dimensions greater than 1.  With few exceptions, a
generalized matrix can be used wherever a matrix can be used.

A generalized matrix with exactly two dimensions with lengths m > 1 and
n > 1, is interpreted as a m by n matrix.  For example, array(run(20),1,
4,1,5) is considered for most purposes as if it were a 4 by 5 matrix.

A generalized matrix whose first dimension is n and all others are 1 is
iterpreted as an n by 1 matrix or, in some contexts, as a vector of
length n.  For example, array(run(7),7,1,1,1) is generally treated as
either a 7 by 1 matrix or a vector of length 7.

A generalized matrix whose first dimension is 1 and which has a single
dimension with length n > 1 is interpreted as a 1 by n matrix, that is,
as a row vector.  For example, array(run(5),1,1,5) is considered to be a
1 by 5 matrix.

A generalized matrix all of whose dimensions are 1 (example:
array(17,1,1,1,1)) is interpreted as a 1 by 1 matrix or, in most
contexts, a scalar.

If x is a generalized matrix, ismatrix(x) returns True and nrows(x) and
ncols(x) return the numbers of rows and columns as just described.

If x is a generalized matrix, matrix(x) is equivalent to matrix(x,
nrows(x)) and is an ordinary two dimensional matrix with the same
elements as x.

@@@@transpose_of_matrix#Transpose of matrix
You can compute the transpose of a matrix x by either x' or t(x).  The
transpose of a generalized matrix is a generalized matrix with the same
dimensions in reverse order.

@@@@multiplying_matrices#Multiplying matrices
You can multiply two REAL matrices or generalized matrices with
conforming dimensions and no MISSING values as follows:
     Operator   Precedence  Meaning
      x %*% y      11       x MatMult y
      x %c% y      11       transpose(x) MatMult y
      x %C% y      11       x MatMult transpose(y)
where MatMult is ordinary matrix multiplication.  The result is always a
matrix with two dimensions, even if either x and.or y is a generalized
matrix.  Either or both operands can also be structures.  See
topic 'structures'.

It formerly was the case on some computers that, when x and y were
large, x' %c% y was considerably faster than x %*% y or x %C% y'.  That
is no longer the case; all three operations take about the same amount
of time.

@@@@dividing_matrices#Dividing matrices
You can "divide" one matrix by another (in the sense of multiplying by
an inverse) if they have conforming dimensions and no MISSING values as
follows:
     Operator   Precedence  Meaning
      x %/% y      11       x MatMult inverse(y) (same as rsolve(y,x)
      x %\% y      11       inverse(x) MatMult y (same as solve(x,y)

Neither %/% or %\% can be used with structures.

Note: These 5 matrix operations are "left associative", that is, for
example that x %*% y %\% z is equivalent to (x %*% y) %\% z, not x %*%
(y %\% z).


@@@@precedence#Precedence
Precedence level 11 is just above the precedence level of '*', '/' and
'%%' and just below the precedence level of '^'.
  Examples:
    Expression          Interpretation     Required to be legal
    a %*% b + 3         (a %*% b) + 3      ncols(a) = nrows(b)
    3 / a %c% b^2       3 / (a %c% (b^2))  nrows(a) = nrows(b)
    a / 3 %C% b         a / (3 %C% b)      ncols(b) = 1

See topic 'precedence' for the precedence levels of other operators.

@@@@functions_useful_with_matrices#Functions useful with matrices
Here are some functions that are useful with matrices.  All treat
generalized matrices as matrices.
  cholesky()                       Compute Cholesky decomposition of x
  det(x)                           Compute the determinant of x
  det(x,mantexp:T)                 Compute the determinant of x in base
                                   10 mantissa and exponent form
  diag(x)                          Extract the diagonal of x.
  eigenvals(x) and eigen(x)        Compute eigenvalues and/or
                                   eigenvectors of x
  hconcat(x,y,...)                 Concatenate x, y, ... horizontally (y
                                   to the right of x, ...)
  nrows(x), ncols(x)               Find the number of rows or columns of
                                   x
  qr(x [,pivot:T])                 Compute QR decomposition of x
  releigenvals(a,b), releigen(a,b) Compute eigenvalues and/or
                                   eigenvectors of a relative to b
  rsolve(a, b)                     Solve x %*% a = b; equivalent to
                                   b %/% a.
  solve(x)                         Invert x
  solve(a,b)                       Solve a %*% x = b; equivalent to
                                   a %\% b.
  svd(x)                           Compute singular value decomposition
                                   of x
  swp(x,intvec)                    Apply Beaton SWP operator to rows
                                   and columns of x specified by intvec
  t(x)  or  x'                     Transpose of x
  trace(x)                         Compute the trace of x
  trideigen(diag,subdiag [,...])   Compute eigenvalues and/or
                                   eigenvectors of symetric tridiagonal
                                   matrix
  vconcat(x,y,...)                 Concatenate x, y, ... vertically (y
                                   below x, ...)

@@@@other_useful_functions#Other useful functions
The following are also useful, but they do not treat a generalized
matrix x exactly like matrix(x).
  max(x)                           Maximum of each column of x
  min(x)                           Minimum of each column of x
  prod(x)                          Product down columns of x
  sum(x)                           Sum down columns of x

These all operate on the first actual dimension of x, producing a result
with the same number of dimensions as x, but with first dimension 1.  If
you want to treat a generalized matrix as if it were a matrix, use, say,
sum(matrix(x)).  See help on the functions for information on how to
operate on dimensions other than the first.

@@@@complex_matrices#Complex matrices
MacAnova stores complex data in REAL matrices in two formats, fully
complex and packed Hermitian.  See topic 'complex' for details of the
format and information about functions useful with complex data.

The following are macros explicitly for working with complex matrices A
and B stored in REAL matrices a and b
  cmatmultc(a,b [,op:OP)    matrix product A %*% B, A %c% B or A %C% B
  ctranspose(a)             A'
  cjtranspose(a)            conj(A)'
  cdiag(a)                  diag(A)
  ctrace(a)                 trace(A)
  ceigen(a)                 eigenvalues and eigenvectors of Hermitian A
  csolve(a)                 inverse of non-singular A
  csubscr(a [,i [,j])       simulated A[], A[i], A[i,], A[,j] or A[i,j]

@@@@see_also#Cross references
See also det(), trace(), swp(), eigen(), eigenvals(), releigen(),
releigenvals(), dim(), nrows(), ncols(), svd(), cholesky().
@@@@______

====matrix()#matrix algebra,variables,combining variables
%%%%
matrix(x,Rowdim [,KeyPhrases]), x a vector, Rowdim > 0 an integer
  dividing length(x)
matrix(x [,KeyPhrases]), x a generalized matrix.
KeyPhrases can be labels:structure(rowLabs,colLabs), notes:Notes and
  silent:T, where rowLabs, colLabs and Notes are CHARACTER scalars or
  vectors.
%%%%
@@@@usage#Usage
matrix(x,Rowdim) creates a matrix (two dimensional array) with Rowdim
rows containing the data in x.  x can be a vector, matrix, or higher
dimensional array, all of whose elements are used, with first subscript
changing fastest, second subscript, if any, changing next, and so on.

Rowdim must be a positive integer exactly dividing the length of vector,
matrix, or array x.

@@@@example#Example
Example:
  Cmd> c <- matrix(vector(1,1,1, -1,1,0, -1,-1,2),3)
creates the following matrix:
            1   -1   -1
       c  = 1    1   -1 .
            1    0    2

@@@@no_dimensions_supplied#No dimensions supplied
matrix(x), with no Rowdim, is equivalent to matrix(x,nrows(x)).  It is
valid for any one- or two-dimensional x, or for any higher dimensional
array with no more than two dimensions greater than 1, that is for any x
such that 'ismatrix(x)' would be True.  See topics ismatrix() and
'matrices'.

Example: h <- matrix(SS[2,,]) creates a true p by p matrix from the 1 by
p by p array SS[2,,], if SS is an array of SSCP matrices created as a
side effect by manova().  See manova().

Although most operations, including matrix multiplication, matrix
inversion, and eigenvalue computation, treat SS[2,,] and matrix(SS[2,,])
identically, there are a few that do not.  Using matrix() can avoid some
surprises.

@@@@labels_and_notes_keywords#Keywords 'labels' and 'notes'
On both usages, you can specify row and column labels for the output
using keywords labels.  See topic 'labels' for details.

You can attach a CHARACTER vector of descriptive notes to the result
using keyword phrase 'notes:Notes'.  See topic 'notes' for details.

When x is a matrix and either Rowdim is not specified or nrows(x) =
Rowdim, any coordinate labels or descriptive notes of x are transferred
to the result unless 'labels' or 'notes' provide new labels or notes or
are NULL.

@@@@see_also#Cross references
See also topics array(), nrows(), 'matrices'.
@@@@______

====matwrite()#files,output
%%%%
matwrite(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.
%%%%
@@@@usage#Usage
matwrite(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'.

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

@@@@matwrite_compared_with_matprint#matwrite() compared with matprint()
matwrite() differs from matprint() only in the default format used for
REAL and LOGICAL variables.  It uses the format used by write(), namely
the format specified by option 'wformat'.  This normally provides 9
significant digits.  It is provided to make it easier for you to write
data sets with increased precision without having explicitly to provide
a format.

@@@@changing_default_format#Changing default format
You can change the default format for write() and matwrite() by
setoptions() using keyword 'wformat'.  See topics setoptions() and
'options'.

@@@@see_also#Cross references
See matprint() for information on keywords 'missing', 'sep', 'name',
'header', 'width', 'quoted', 'bylines', and 'comments', macrowrite() for
information on 'oldstyle' and 'stripdols', and print() for information
on keywords 'nsig' and 'format'.

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

See also topics print(), write(), matwrite(), macrowrite(), read(),
matread(), 'files'.
@@@@______

====max()#descriptive statistics
%%%%
max(x [,squeeze:T] [,silent:T,undefval:U]), x REAL or LOGICAL or a
  structure with REAL or LOGICAL components, U a REAL scalar
max(x, dimensions:J [,squeeze:T] [,silent:T,undefval:U]), vector of
  positive integers J
max(x, margins:K [,squeeze:F] [,silent:T,undefval:U]), vector of
  positive integers K
max(x1,x2,... [,silent:T,undefval:U]), x1, x2, ... REAL or LOGICAL
  vectors, all the same type.
%%%%
@@@@usage#Usage
max(x) computes the maximum of the elements of a REAL or LOGICAL vector
x.

If x is LOGICAL, True is interpreted as 1.0 and False as 0.0 and hence
max(x) is 1.0 if any element of x is True, and 0.0 if all elements are
False.

If x is a m by n matrix, max(x) computes a row vector (1 by n matrix)
consisting of the maxima of the elements in each column of x.

If x is an array with dimensions n1, n2, n3, ..., y <- max(x) computes
an array with dimensions 1, n2, n3, ... such that y[1,j,k,...] =
max(x[i,j,k,...], i=1,...,n1).  This is consistent with what happens
when x is a matrix.  Note: MacAnova3.35 and earlier produced a result
with dimensions n2, n3, ... .

max(x, squeeze:T) does the same, except the first dimension of the
result (of length 1) is squeezed out unless the result is a scalar.  In
particular, if x is a matrix, max(x,squeeze:T) will be identical to
vector(max(x)), and if x is an array, max(x,squeeze:T) will be identical
to array(max(x),dim(x)[-1]).

max(NULL) is NULL.

max(a,b,c,...) is equivalent to max(vector(a,b,c,...)) if a, b, c,
... are all vectors.  They must all have the same type, REAL or LOGICAL,
or be NULL.  max(NULL,NULL,...,NULL) is NULL.

min(x, silent:T) or min(a,b,c,...,silent:T) does the same but suppresses
warning messages about MISSING values.

If all the elements of a vector x are MISSING, max(x) is MISSING.

max(x, undefval:U), where U is a REAL scalar does the same, except the
returned value is U when all the elements of x are MISSING.

@@@@dimensions_keyword#Keyword 'dimensions'
max(x, dimensions:J [,squeeze:T] [,silent:T] [undefval:U]) finds the
maximum over the dimensions in J = vector(j1,j2,...,jn) where j1, ...,
jn are distinct positive integers <= ndims(x).  Without 'squeeze:T', the
result has the same number of dimensions as x, with dimensions j1, j2,
..., jn of length 1.  With 'squeeze:T', these dimensions are removed
from the result.  The order of j1, j2, ... is ignored.

It is an error if max(J) > ndims(x) or if there are duplicate elements
in J.

For example, if x is a matrix, max(x, dimensions:2) computes the row
maxima as a nrows(x) by 1 matrix and max(x, dimensions:2,squeeze:T)
computes them as a one dimensional vector.

@@@@margins_keyword#Keyword 'margins'
max(x, margins:K [,squeeze:F] [,silent:T] [undefval:U]) finds the maxima
over the dimensions not in K = vector(k1, k2, ..., km), where k1, ...,
km are distinct positive integers <= ndims(x).  This computes maxima for
the margins specified in K.

Without 'squeeze:F', only the dimensions in K are retained in the
result.  Otherwise the other dimensions are retained but have length 1.
This is opposite from the default with 'dimensions:J'.

It is an error if max(K) > ndims(x) or if there are duplicate elements
in K.

@@@@structure_argument#Structure argument
If x is a structure, max(x [dimensions:J or margins:K] [,squeeze:T or F]
[,silent:T] [undefval:U]) computes a structure, each of whose components
is max() applied to that component of x.

@@@@example#Example
Examples:
  Cmd> x # matrix with labels
              B1          B2
  A1          18          15
  A2          17          26
  A3          18          19

  Cmd> max(x) # maxima down columns
               B1          B2
  (1)          18          26

  Cmd> max(x,dimensions:2) # maxima across rows; 3 by 1 matrix
             (1)
  A1          18
  A2          26
  A3          19

  Cmd> max(x,dimensions:2,squeeze:T) # same, length 3 vector
            A1          A2          A3
            18          26          19

  Cmd> max(x,margins:1) # same as preceding
            A1          A2          A3
            18          26          19

@@@@example#Example
See also topics min(), 'NULL'.
@@@@______

====memory%#general
%%%%
Type help(memory) for information related to memory usage
%%%%
@@@@memory_usage_information#Memory usage information
The MacAnova "workspace", (all variables and macros; see topic
'workspace'), "resides" in memory (RAM) and not on your hard disk.

You can use keyword phrase size:T on list() to get information on the
amount of memory used by individual variables and the total used by all
variables and internal MacAnova storage.  This does not include the
memory required for the program itself nor, in a windowed version,
memory associated with windows and graphs.  See list().

memoryinfo() returns a vector summarizing several aspects of memory
usage.  See memoryinfo() for details.

@@@@not_enough_memory_problem#Not enough memory problem
Because RAM is a finite resource, you may sometimes be unable to carry
out a computation because there is no room for intermediate and/or final
results.  When this happens you get a message similar to the following:
   ERROR: Not enough memory.  Try deleting variables

When this happens, use delete() to get rid of the largest variables you
can do without.  If you really need to keep them, use save() or
asciisave() to save some or all of your variables on disk before
deleting them.
  Cmd> save("myvars.sav", x, y, residplot:LASTPLOT)

  Cmd> delete(x, y, LASTPLOT)

@@@@other_work_arounds#Other work arounds
You can free up memory used to store information related to the most
recent GLM command such as regress() or anova() by
  Cmd> delete(STRMODEL)
This will make certain functions such as secoefs() and modelinfo()
unavailable until after another GLM command.

In Windowed versions, memory can sometimes be made available by closing
unneeded graphics and/or command/output windows.

@@@@comparison_of_versions#Comparison of versions
The amount of memory available for individual variables and the entire
workspace differs between versions, primarily because of differences in
operating systems.

All versions have no effective limit on the size of variables other than
the availability of memory on your computer.

The Macintosh classic (OS 9) version runs in its own memory "partition".
When MacAnova is launched, its partition is allocated a specific amount
of space for program and data and MacAnova cannot exceed the limit, even
if a lot more memory is installed.  When the limit is, say, 1000 KB
(1 KB is 1024 bytes), then MacAnova has N KB for variables, where,
because memory is needed for the program, N in the neighborhood of 600.
When the limit is 2500 KB = (1000 + 1500) KB, then MacAnova has N + 1500
KB of memory for its workspace.  When the partition is allocated 5000 KB
= (1000 + 4000) KB, available memory is N + 4000 KB, and so on.

@@@@changing_macintosh_partition_size#Changing Macintosh partition size
As distributed, the Mac OS 9 version of MacAnova has a default maximum
partition size of 5000 KB.  However, it is quite easy to change the
limit from the Finder.  Open the folder where MacAnova is installed and
select the MacAnova icon with the mouse.  Select Get Info on the File
menu to display a dialog box containing a 'Show:' popup menu on which
you should select 'Memory'.  This will display a Memory Requirements
panel.  (In older systems, the Memory Requirements panel may be
immediately displayed by Get Info.)  Type a new number in the "Suggested
size" box to set a new maximum partition size and then close the dialog
box.  That's all there is to it.

@@@@see_also#Cross references
See also topics delete(), save(), asciisave(), 'workspace'
@@@@______

====memoryinfo()#general
%%%%
memoryinfo()
%%%%
@@@@usage#Usage
info <- memoryinfo() sets info to a vector of length 5 containing the
following information about memory usage:
  info[1]   Total memory used by named variables, excluding built-in
            functions but including macros and special variables such as
            CLIPBOARD and GRAPHWINDOWS
  info[2]   Total memory currently used by scratch variables.  This
            includes the results of any computations not yet in named
            variables but not scratch variables used in invoking
            memoryinfo()
  info[3]   Total memory currently used by internal copies of what was
            typed at the prompt
  info[4]   Total memory allocated by MacAnova.  This excludes memory
            required by the program itself and some memory that is
            allocated at the start and kept for the entire run.  On
            windowed system, it excludes memory for command and graphics
            windows and menus.
  info[5]   The maximum memory so far allocated by MacAnova, always >=
            info[4]

The values returned are the number of bytes used or allocated.

memoryinfo() is primarily useful in (a) tracking down bugs in memory
allocation by MacAnova itself, and (b) determining why a macro uses more
memory than you think it ought to.

@@@@see_also#Cross references
See also topic 'memory'.
@@@@______

====min()#descriptive statistics
%%%%
min(x [,squeeze:T] [,silent:T,undefval:U]), x REAL or LOGICAL or a
  structure with REAL or LOGICAL components, U a REAL scalar
min(x, dimensions:J [,squeeze:T] [,silent:T,undefval:U]), vector of
  positive integers J
min(x, margins:K [,squeeze:F] [,silent:T,undefval:U]), vector of
  positive integers K
min(x1,x2,... [,silent:T,undefval:U]), x1, x2, ... REAL or LOGICAL
  vectors, all the same type.
%%%%
@@@@usage#Usage
min(x) computes the minimum of the elements of a REAL or LOGICAL vector
x.

If x is LOGICAL, True is interpreted as 1.0 and False as 0.0 and hence
min(x) is 0.0 if any element of x is False, and 1.0 if all elements are
True.

If x is a m by n matrix, min(x) computes a row vector (1 by n matrix)
consisting of the minima of the elements in each column of x.

If x is an array with dimensions n1, n2, n3, ..., y <- min(x) computes
an array with dimensions 1, n2, n3, ... such that y[1,j,k,...] =
min(x[i,j,k,...], i=1,...,n1).  This is consistent with what happens
when x is a matrix.  Note: MacAnova3.35 and earlier produced a result
with dimensions n2, n3, ... .

min(x, squeeze:T) does the same, except the first dimension of the
result (of length 1) is squeezed out unless the result is a scalar.  In
particular, if x is a matrix, min(x,squeeze:T) will be identical to
vector(min(x)), and if x is an array, min(x,squeeze:T) will be identical
to array(min(x),dim(x)[-1]).

min(NULL) is NULL.

min(a,b,c,...) is equivalent to min(vector(a,b,c,...)) if a, b, c,
... are all vectors.  They must all have the same type, REAL or LOGICAL,
or be NULL.  min(NULL, NULL, ..., NULL) is NULL.

min(x, silent:T) or min(a,b,c,...,silent:T) does the same but suppresses
warning messages about MISSING values.

If all the elements of a vector x are MISSING, min(x) is MISSING.

min(x, undefval:U), where U is a REAL scalar does the same, except the
returned value is U when all the elements of x are MISSING.

@@@@dimensions_keyword#Keyword 'dimensions'
min(x, dimensions:J [,squeeze:T] [,silent:T] [undefval:U]) finds the
minimum over the dimensions in J = vector(j1,j2,...,jn) where j1, ...,
jn are distinct positive integers <= ndims(x).  Without 'squeeze:T', the
result has the same number of dimensions as x, with dimensions j1, j2,
..., jn of length 1.  With 'squeeze:T', these dimensions are removed
from the result.  The order of j1, j2, ... is ignored.

It is an error if max(J) > ndims(x) or if there are duplicate elements
in J.

For example, if x is a matrix, min(x, dimensions:2) computes the row
minima as a nrows(x) by 1 matrix and min(x, dimensions:2,squeeze:T)
computes them as a one dimensional vector.

@@@@margins_keyword#Keyword 'margins'
min(x, margins:K [,squeeze:F] [,silent:T] [undefval:U]) finds the minima
over the dimensions not in K = vector(k1, k2, ..., km), where k1, ...,
km are distinct positive integers <= ndims(x).  This computes minima for
the margins specified in K.

Without 'squeeze:F', only the dimensions in K are retained in the
result.  Otherwise the other dimensions are retained but have length 1.
This is opposite from the default with 'dimensions:J'.

It is an error if max(K) > ndims(x) or if there are duplicate elements
in K.

@@@@structure_argument#Structure argument
If x is a structure, min(x [dimensions:J or margins:K] [,squeeze:T or F]
[,silent:T] [undefval:U]) computes a structure, each of whose components
is min() applied to that component of x.

@@@@example#Example
Examples:
  Cmd> x # matrix with labels
              B1          B2
  A1          18          15
  A2          17          26
  A3          18          19

  Cmd> min(x) # minima down columns
               B1          B2
  (1)          17          15

  Cmd> min(x,dimensions:2) # minima across rows; 3 by 1 matrix
             (1)
  A1          15
  A2          17
  A3          18

  Cmd> min(x,dimensions:2,squeeze:T) # same, length 3 vector
            A1          A2          A3
            15          17          18

  Cmd> min(x,margins:1) # same as preceding
            A1          A2          A3
            15          17          18

@@@@see_also#Cross references
See also topics max(), 'NULL'.
@@@@______

====modelinfo()#glm
%%%%
modelinfo([all:T] keyword1:T or F, keyword2:T or F ...[,nomodelok:T]\
  [,missing:missvalue]), missvalue a REAL scalar and the keywords
  are one or more of 'aliased', 'bitmodel', 'coefs', 'colcount',
  'distrib', 'link', 'parameters', 'scale', 'sigmahat' 'strmodel',
  'termnames', 'weights', 'xtxinv', 'xvars', and 'y'
%%%%
@@@@usage#Usage
modelinfo(keyword1:T, keyword2:T, ... ) computes one or more vectors or
matrices associated the most recent GLM (generalized linear or linear
model) command such as regress(), anova(), poisson(), or glmfit().  This
gives you direct access to such things as the design variables or
X-variables (xvars:T), the estimated coefficients of the X-variables
(coefs:T), and the inverse of the X'X matrix (xtxinv:T).

Permissible keyword names specifying quantities returned are 'aliased',
'bitmodel', 'coefs', 'colcount', 'distrib', 'link', 'parameters',
'scale', 'sigmahat' 'strmodel', 'termnames', 'weights', 'xtxinv',
'xvars', and 'y'.  You can also use 'all:T'; see below.

You can't use modelinfo() after fastanova(), ipf(), or screen().

Any component requested that is not available is set to NULL.  In
particular this happens for components 'coefs' and 'xtxinv' after
anova() when the model is balanced, or after any GLM command with
'coefs:F', and for component parameters after any GLM for which a sample
size or other parameter is specified such as for logistic() and
probit().

When more than one of the keywords specifying type of output has value
True, modelinfo() returns a structure with component names the same as
the keywords.  Otherwise it returns a vector or matrix.

@@@@missing_keyword#Keyword 'missing'
modelinfo(xvars:T, ..., missing:missval) returns the matrix of
X-variables associated with the active model with all the values for a
case in which there was missing data set to REAL scalar missval.  The
default value is 0.

@@@@all_and_nomodelok_keywords#Keywords 'all' and 'nomodelok'
modelinfo(all:T) is equivalent to modelinfo(xvars:T,y:T,coefs:T,
xtxinv:T,colcount:T,weights:T,parameters:T,strmodel:T,bitmodel:T,
termnames:T, scale:T, sigmahat:T,aliased:T).  To suppress any particular
components, say 'strmodel', 'bitmodel', and 'termnames', use
modelinfo(all:T, strmodel:F,bitmodel:F,termnames:F).  Use of all:F is an
error.

Normally, it is an error if there is no active GLM model.  However, if
nomodelok:T is an argument, when there is no active model modelinfo()
returns NULL without printing an error message.  For example, you can
test for the existence of an active model by

  Cmd> if(isnull(modelinfo(strmodel:T,nomodelok:T))){...do something...}

You can use 'nomodelok:T' with any of the keywords specifying components
to return.

See isnull().

                      Permissible Keyword Phrases
@@@@aliased_keyword#Keyword 'aliased'
   aliased:T
     A LOGICAL vector whose length is the number of X-variables in the
     model.  The i-th variable is True if and only if the i-th
     X-variables as returned by xvars:T is aliased with previous
     X-variables.  If there was no aliasing every element should be
     False.

@@@@bitmodel_keyword#Keyword 'bitmodel'
   bitmodel:T
     A REAL vector or matrix with as many rows as there are terms in the
     model, including the CONSTANT term, if any, but excluding the final
     error term.  This encodes the model in a special form.  See below
     for details.

@@@@coefs_keyword#Keyword 'coefs'
   coefs:T
     The vector of coefficients of the X-variables in the fitted model.
     Coefficients corresponding to aliased X-variables (those that are
     apparently linearly dependent on previous X-variables) are set to
     zero.  After manova() with a p-dimensional response matrix, the
     coefficients form a matrix with p columns.  Note: If there are
     factors in the model, some of the coefficients computed will differ
     from the coefficients computed by coefs() and secoefs().

@@@@colcount_keyword#Keyword 'colcount'
   colcount:T
     A REAL vector containing the numbers of X-variables assocated with
     each term in the active model.  The numbers of the first column
     associated with each term can be obtained by autoreg(1,
     modelinfo(colcount:T)).  If no X-variables are aliased with earlier
     X-variables, these values are the degrees of freedom associated
     with each term.

@@@@parameters_keyword#Keyword 'parameters'
   parameters:T
     A REAL vector containing the sample sizes or other distribution
     parameters after logistic() or probit(), or after glmfit() with
     keywords n or parameters.

@@@@scale_keyword#Keyword 'scale'
   scale:T
     A REAL factor or factors to multiply the square roots of the
     diagonals of the inverse of the X'X matrix so as to obtain
     estimated standard errors for the estimated coefficients.  After
     logistic(), poisson(), probit(), or glmfit(), scale will be the
     default value, unless changed by keyword 'scale' on the GLM
     command.  After other GLM commands, including robust(), scale will
     be sqrt(SSerror/DFerror), where DFerror and SSerror come from the
     final line of the ANOVA table.  After manova(), scale will be the
     vector consisting of the square roots of diagonal elements of
     SSerror/DFerror, where SSerror is the error matrix.

@@@@sigmahat_keyword#Keyword 'sigmahat'
   sigmahat:T
     The robust estimate of sigma printed after the robust() ANOVA
     table.  It is not usable after any other GLM command.  Note that
     this is not a suitable value to use in computing standard errors.

@@@@strmodel_keyword#Keyword 'strmodel'
   strmodel:T
     A CHARACTER variable containing the current model taken from
     STRMODEL.

@@@@termnames_keyword#Keyword 'termnames'
   termnames:T
     A CHARACTER vector of the terms in the model taken from TERMNAMES.
     This includes the name (usually "ERROR1") of the final error term,
     and thus the length of the result is 1 greater than the number of
     rows in modelinfo(bitmodel:T).

@@@@weights_keyword#Keyword 'weights'
   weights:T
     A REAL vector containing the weights associated with each case.  If
     there are no missing data and no weights were specified, either
     explicitly or implicitly, this is a vector of 1's.  Otherwise it
     contains either the weights specified by keyword 'weights' or 'wts'
     in anova(), manova() or regress() or the implicit weights from the
     final iteration of poisson(), logistic(), or robust().  The weight
     for any case with MISSING data is always zero.

@@@@xtxinv_keyword#Keyword 'xtxinv'
   xtxinv:T
     The inverse of the X'X matrix computed from the X-variables.  The
     row and column corresponding to any aliased X-variable is set to
     zero.  If the previous GLM command specified weights either
     explicitly (keyword 'weights' or 'wts' on anova(), regress(),
     manova()) or implicitly (poisson() or logistic()) the matrix
     computed is the inverse of X'WX, where W is the diagonal matrix of
     the weights.  After robust(), the matrix computed is the inverse of
     X'X, ignoring the implicit weights.  The weights may be obtained by
     keyword phrase weights:T (see above).

@@@@xvars_keyword#Keyword 'xvars'
   xvars:T
     The matrix of X-variables associated with the active model.  If
     there is no active model, but STRMODEL is defined and there are no
     other keywords, it works identically to xvariables().

     When 'missing:missValue' is an argument, where missValue is a REAL
     scalar, the X-variable values for a case with any missing data will
     be set to missValue.  In particular, you can used 'missing:?' to
     set the X-variables for a case with MISSING data to MISSING.  The
     default value is 0.  See xvariables() for more information.

@@@@y_keyword#Keyword 'y'
   y:T
     The dependent variable in the model as a vector or matrix.
     modelinfo(y:T) is thus equivalent to modelvars(0).

@@@@bitmodel_keyword_more#More on keyword 'bitmodel'
Each row of modelinfo(bitmodel:T) corresponds to a term in the model and
consists of one or more integers between 0 and 4294967295 = 2^32 - 1,
the bits of whose binary representation encode the variates and/or
factors in that term.  If there are 33 to 64 or 65 to 95 variates and
factors, the result is a matrix with 2 or 3 columns.  Thus each row of
the output has room for Nvar bits, where Nvar is the number of variates
and/or factors in the model.

The bits of each row should be considered to be numbered from 1 to Nvar.
Bit 1 is the least significant and bit 32 is the most significant bit of
the first element; bit 33 is the least significant and bit 64 is the
most significant bit of the second element, if any; and bit 65 is the
least significant and bit 96 is the most significant bit of the third
element, if any.  Bit i of row j of the result is 1 if and only if the
i-th variable or factor is in the j-th term of the model, following the
order in which variables and factors first appear in the model.  All the
elements in a row corresponding to the CONSTANT term (usually row 1) are
zero.

@@@@see_also#Cross references
See topics 'bit_ops' and nbits() for information on how to extract
information from the result of modelinfo(bitmodel:T).

See also topics varnames(), modelvars(), xvariables(), coefs(),
secoefs(), glmpred(), glmtable(), regpred(), predtable(), popmodel(),
pushmodel(), 'models'.
@@@@______

====models#glm,anova,regression
%%%%
Regression:  regress("y=x1+x2+...+xk")
One-way ANOVA: anova("y=A"), factor A
Randomized block ANOVA: anova("y=Repl+A"), factors Repl and A
Nested ANOVA: anova("y=A/B") or anova("y=A+A.B")
Two-way factorial: anova("y=A*B") or anova("y=A+B+A.B"), factors A and B
Completely randomized Split plot ANOVA: anova("y=A+E(Repl.A)+B+A.B"),
  factors A, B, and Repl
Analysis of covariance: anova("y=x+A"), factor A, variate x
Transform variables on the fly: regress("{log10(y)}={sqrt(x)}")
Polynomial regression: regress("y=P3(x)")
Periodic regression: regress("y=C2(2*PI*hour/24)")
%%%%
@@@@form_of_glm_model#Form of GLM model
All of the GLM (generalized linear or linear model) commands such as
regress(), anova(), or poisson() require you to specify a model in a
quoted string or CHARACTER variable.

A model can be specified as
   "Response = Term"   or   "Response = Term1 + Term2 + ..."
where 'Response' is the name of the dependent or response variable
and each term is of the form Name or Name1.Name2. ... .Namek, where
Name, Name1, Name2 ... are the names of variables.  A period or dot (.)
between the variable names is interpreted as a product operator
indicating that all combinations of the variable values are included in
the model.

@@@@model_variables
                            Model Variables
Variables in model terms, including those computed on the fly (see
below), may be either factors (vectors of positive integers created
using factor()) or variates.  No more than one variate may appear in a
single term.  Up to 95 variables may appear in a model, including no
more than 31 factors.

Factors and variates must be vectors or matrices with one column.  They
must all have the same number of rows as the response variable.

Any factors must have been created using factor() or been selected from
such a variable using subscripts.  For balanced designs with factor
levels in a reasonable order a factor may often be computed by
factor(rep(run(r),s)), factor(rep(run(s), rep(r,s))), or something
similar.  See factor(), rep().

The constant term may be specified as 1, but is always included by
default, that is "y = Model" is equivalent to "y = 1 + Model".  You can
omit a constant term by "y = Model - 1" or move it to the end by
"y = Model - 1 + 1".

@@@@on_the_fly_transforming
                    Computing Variables "on the fly"
You can transform or otherwise compute model variables "on the fly."  In
place of the name of a variable, including the response variable, you
can use {Expr}, where Expr is a MacAnova expression such as x^2 or
log10(y).  If the same expression, say {sqrt(x)}, appears more than once
in a model, it is evaluated only once and only one model variable is
introduced.  In comparing expressions, leading and trailing spaces are
ignored, so that { sqrt(x) } is considered the same as {sqrt(x)};
however, other differences in the presence or placement of spaces will
cause expressions to be considered different variables.  For example,
{sqrt( x)} is not recognized to be the same as {sqrt(x)}.  The only
limitation on Expr is that it may not directly or indirectly execute
another GLM command.

Since subscripted factors remain factors (see 'subscripts'), when groups
is a factor, anova("{y[-3]} = {groups[-3]}") computes a one factor
analysis of variance omitting case 3.

@@@@examples_1
                                Examples
a and b are factors and y, x1, x2, and x3 are REAL vectors
   Model                       Description
   "y = a + b + a.b"           Two factor model with both main effects
                               and interaction
   "y = a + a.b"               Two factor model with b nested in a
   "y = x1 + x2 + x3"          Three variable multiple regression
   "{sqrt(y)} = x1 + {x1^2}"   2nd order polynomial regression of square
                               root of y on x.

@@@@polynomial_and_periodic_regression_shortcuts
            Shortcuts for Polynomial and Periodic Regression
You can use special short cuts of the form Pn(expr) and Cn(expr) to
specify a polynomial term or a periodic term, respectively, where n is
an integer between 1 and 95 and expr is a MacAnova expression.  For
example, P4(x-10) expands to ({x-10}+{(x-10)^2}+{(x-10)^3}+{(x-10)^4})
and C2(2*PI*x/24) expands to ({cos(2*PI*x/24)}+{sin(2*PI*x/24)}+
{cos(2*(2*PI*x/24))}+{sin(2*(2*PI*x/24))}).

Pn(expr) and Cn(expr) can be used wherever a variable name can be used
on the right side of '=', except not in a {...} expression.  Thus the
last example in the preceding list could have been written "{sqrt(y)} =
P2(x1)".  They can be "dotted" with a factor.  For example, P2(x).a
expands to {x}.a + {(x)^2}.a.

If you are doing a regression on a subset of cases uses subscripts, the
subscripts must be applied to x, not Cn(x) or Pn(x).  For example,
  Cmd> regress("{y[-run(3)]} = P3(x[-run(3)])")
fits a cubic polynomial omitting the first 3 rows of x and y.

See below for other shortcuts you can use to specify models.

@@@@combining_variables
                          Combining Variables
Parts of terms can be replaced by 'submodels', enclosed in
parentheses, for example,
  Cmd> anova("y = a + b + c + d + (a + b).(c + d)")
is equivalent to
  Cmd> anova("y = a + b + c + d + a.c + b.c + a.d + b.d")

The product of a factor or variate with itself (a.a) is equivalent to
the variate or factor itself.  For example,
  Cmd> anova("y = (a + b).(a + c)")
is equivalent to
  Cmd> anova("y = a + b.a + a.c + b.c")

The order of factors and variates in a term is immaterial.  That is a.b
is equivalent to b.a.

@@@@order_of_terms#Order of terms
The order of terms in a model is very important since fitting a model is
done sequentially, term by term.  For example, although "y = a + a.b" is
a model with b nested in a, "y = a.b + a" is computationally equivalent
to "y = a.b", since after fitting all combinations of a and b, there is
nothing left for 'a' to fit.

If a term in a model is duplicated, only the first occurrence is
retained.  For example, (a + b).(a + b) expands to a.a + b.a + b.a + b.b
which is equivalent to a + a.b + a.b + b which is trimmed to a + a.b + b
(which is computationally equivalent to a + a.b).

                    Order of terms in expanded models
If M1, M2, ..., Mk, N1, N2, ..., Nl are terms or submodels,
(M1 + M2 + ... + Mk).(N1 + N2 + ... + Nl) is equivalent to
M1.N1 + M2.N1 + ... + Mk.N1 + M1.N2 + M2.N2 + ... + Mk.N2 + ... + Mk.Nl

If M1, M2, ..., Mk are terms or submodels, M1.M2.M3. ... .Mk is expanded
as (...((M1.M2).M3) ... ).Mk.

@@@@short_cuts
            Short cut formulas for combining terms or submodels
In the following, M1, M2, ... are terms or submodels.

M1*M2 is an abbreviation for M1 + M2 + M1.M2

M1*M2* ... *Mk is an abbreviation for (...((M1*M2)*M3) ... )*Mk.  In
  particular, M1*M2*M3 is an abbreviation for (M1*M2)*M3, that is for
  M1 + M2 + M1.M2 + M3 + M1.M3 + M2.M3 + M1.M2.M3

M1^N is an abbreviation for M1.(1+M1). ... .(1+M1), where there are N
  factors.  N must be a digit between 1 and 31.  This contains the same
  terms as M1*M1*...*M1 (N factors) but in a different order.  For
  example, (a+b+c+d)^4 has main effects followed by 2-way interactions
  followed by 3-way interactions followed by a.b.c.d.  Note that M1^N is
  usually not equivalent to and does not contain the same terms as
  M1. ... .M1 (N dot factors).

M1/M2 is an abbreviation for M1 + MM1.M2 where MM1 has the form
  a.b. ... .z, where a, b, ..., z are all the factors and/or variates in
  M1.  For example, (a+b+c)/(d+e) is equivalent to a+b+c+a.b.c.d+
  a.b.c.e.  Note: Earlier versions of help and other documentation had a
  different definition which was correct only in some common simple
  cases.

M1 - M2 is an abbreviation for a model containing all the terms in M1,
  omitting any term in M2.  In particular Model - 1 specifies a model
  with no constant term or intercept and Model - 1 + 1 specifies a model
  with a contant term that is fit after all other terms in Model.

M1 -* M2 is an abbreviation for a model containing all the terms in M1,
  but omitting any terms containing all the variables in any term of M2.

@@@@examples_of_short_cut_use#Examples of use of shortcuts
   "y = a*b" is equivalent to "y = a + b + a.b"
   "y = a/b" is equivalent to "y = a + a.b"
   "y = a*b*c" is equivalent to "y = a + b + a.b + c + a.c + b.c +
       a.b.c"
   "y = (a+b+c)^2" is equivalent to "y = a + b + c + a.b + a.c + b.c"
   "y = (a+b+c)^3" is equivalent to "y = a + b + c + a.b + a.c + b.c +
       a.b.c"
   "y = a*b*c - a.b.c" is equivalent to "y = a + b + a.b + c + a.c +
       b.c"
   "y = a*b*c -* (a.b + a.c)" is equivalent to "y = a + b + c + b.c"

Note the order of the exanded terms.  In particular, observed that,
although "y=a*b*c" and "y=(a+b+c)^3" contain the same terms when
expanded, they are in a different order.

@@@@error_terms
                              Error Terms
In the output from commands such as anova() or poisson() that produce an
analysis of variance or deviance table, there is always one line,
usually labeled "ERROR1", following all the terms explicitly or
implicitly specified in Model.  It consists of the sum of squares or
deviance associated with all the degrees of freedom not included in the
model.  If the model fitted uses up all the degrees of freedom this line
will still be present, but will have 0 degrees of freedom.

You can also label other terms as ERROR.  If a term is of the form
E(Term) (for example, E(a.b.c)), it will be labeled "ERRORn" in the
ANOVA table, where n is 1, 2, ..., .  The final error line will still be
printed but will be labeled "ERRORm", where m-1 is the number of error
terms you specified.  E(1) is not legal, nor is it legal to specify a
term as an error term more than once (E(a.b) + E(a.b)).  Moreover, once
a term is designated as an error term, it cannot be deleted by '-' or
'-*'.  Term in E(term) must be a single factor or a pure product of
factors.  For example, E(a.b+a.b.c) is illegal.

@@@@comments_in_models#Comments in models
A '#' in Model marks the end of the model, allowing models to be self-
documenting as in anova("y = a + b #additive model").

@@@@variable_STRMODEL#Variable STRMODEL
Any GLM command sets the CHARACTER variable STRMODEL to the specified
model as a "side effect" of the analysis.  If no model is specified on a
subsequent GLM commands (for example anova()), it is taken from this
variable.  Alternatively, if you set STRMODEL directly, for example
  Cmd> STRMODEL <- "y = x1 + x2 + x3"
then the value of STRMODEL will be used by the next GLM command if it
has no model as argument.  Note, however, when you assign a value to
STRMODEL, MacAnova discards the internal information saved by the most
recent GLM command that is used by functions such as secoefs() and
contrast().

@@@@examples_2
                         Examples of GLM Models
  Cmd> anova("y = a + b + a.b") # or anova("y = a*b")
will produce a two-way analysis of variance with interaction for the
response in y, provided vector y is defined and a and b are factors with
the same length as y.

  Cmd> anova("y = a + a.b") # or anova("y = a/b")
where a and b are factors will produce a nested analysis of variance
with b nested within a.

  Cmd> anova("y = blk + a + E(a.blk) + b + a.b")
would be appropriate for the analysis of a two factor split plot
experiment with the whole plot treatments in a randomized block design.
Do not attempt to use the name 'rep' for a blocking factor, since 'rep'
is the name of a built-in operation.
@@@@______

====modelvars()#glm
%%%%
modelvars(varList [,Model]), varList a vector of integers >= 0, Model a
  CHARACTER scalar
modelvars(y:T or x:T or variates:T or factors:T or all:T [, Model])
modelvars(nx:T or nvariates:T or nfactors:T or hasconst:T [, Model])
%%%%
@@@@usage#Usage
modelvars(VarList,Model), where VarList is a vector of non-negative
integers, say vector(i1,i2,i3,...), returns a vector or matrix whose
columns are the variables in the model specified by the scalar CHARACTER
variable or quoted string Model.  Variable 0 is the dependent variable
(the variable before '=' in Model) and, if i > 0, variable i is the i-th
variate or factor appearing on the right hand side of Model (after '=').

See topic 'models' for information on specifying Model.

@@@@x_and_y_keywords#Keywords 'x' and 'y'
modelvars(y:T,Model) returns a vector or matrix containing the dependent
variable of Model.  This usage yields the same result as modelvars(0,
Model).

modelvars(x:T,Model) returns a vector or matrix containing the
independent variates and factors of on the right hand side of Model.
This yields the same as modelvars(run(nv), Model), where nv is the
number of variates and factors.  When there are no variates and factors
("y=1"), NULL is returned.  See topic 'NULL'.  See keyword 'nx' below
for determining the total number of variates and factors.

@@@@factors_and_variates_keywords#Keywords 'factors' and 'variates'
modelvars(factors:T,Model) returns a vector or matrix containing the
factors on the right hand side of Model.  When there are no factors in
the model, NULL is returned.  See keyword 'nfactors' below for
determining the total number of factors.

modelvars(variates:T,Model) returns a vector or matrix containing the
variates on the right hand side of Model.  When there are no variates in
the model, NULL is returned.  See keyword 'nvariates' below for
determining the total number of variates.

@@@@all_keyword#Keyword 'all'
modelvars(all:T,Model) returns a matrix containing the dependent
variable followed by the independent variates and factors of Model.
Equivalent to this is modelvars(run(0,nv),Model).

@@@@omitted_model#Omitted model
When Model is omitted (modelvars(VarList) or modelvars(keyword:T)),
variables are taken from internal copies of the variables in the current
active model.  This allows retrieval of the dependent variable and/or
model variables even if they were temporary variables (their names
started with '@').  When there is no active model but variable STRMODEL
exists, modelvars(keyword:T) and modelvars(VarList) are equivalent to
modelvars(keyword:T,STRMODEL) and modelvars(VarList,STRMODEL).  Here
keyword is one of 'x', 'y', 'factors', 'variates', or 'all'.

@@@@examples_1#Examples
    modelvars(vector(1,2,0),"y=x+a") is equivalent to hconcat(x,a,y)
    modelvars(x:T,"y=x+a+a.x") is equivalent to hconcat(x,a)
    modelvars(all:T,"y=x1+x2") is equivalent to hconcat(y,x1,x2)

Note: Any variables that are factors are returned unchanged.  This is
very different from xvariables(), which computes dummy X-variables
associated with a factor.

@@@@counting_factors_and_variables
                     Counting Factors and Variables
You can also use modelvars() to determine how many factors and variates
there are in a model or to check whether the constant term is in the
model.  This can be useful in a macro using the results of a GLM command
to do further analyses.

modelvars(nx:T [,Model]) returns the number of independent variates and
factors on the right hand side of Model, that is, what would be computed
by ncols(modelvars(x:T [,Model])).  When there are no variates and
factors ("y=1"), 0 is returned.

modelvars(nfactors:T [,Model]) returns the number of factors on the
right hand side of Model, that is, what would be computed by
ncols(modelvars(factors:T, [,Model])).  When there are no factors 0 is
returned.

modelvars(nvariates:T [,Model]) returns the number of variates on the
right hand side of Model, that is, what would be computed by
ncols(modelvars(variates:T [,Model])).  When there are no variates 0 is
returned.

modelvars(hasconst:T [,Model]) is True if and only if the constant term
is in the model.

@@@@examples_2#Examples
  Cmd> x <- run(4);y <- rnorm(4)

  Cmd> a <- factor(1,1,2,2); b <- factor(1,2,1,2)

  Cmd> modelvars(nfactors:T,"y=x+a+b+a.x")
  (1)           2

  Cmd> modelvars(nvariates:T,"y=x+a+b+a.x")
  (1)           1

  Cmd> modelvars(nx:T,"y=x+a+b+a.x")
  (1)           3

  Cmd> modelvars(hasconst:T, "y=x")
  (1) T

  Cmd> modelvars(hasconst:T, "y=x-1")
  (1) F

@@@@see_also#Cross references
See also topics 'models', varnames(), xvariables().
@@@@______

====more()#output,general
%%%%
more(x [, nsig:n, format:Fmt, missing:M ,stripdol:T]), where x is a
  macro or is a REAL, CHARACTER, or LOGICAL variable, n > 0 is an
  integer, Fmt and M are CHARACTER scalars
%%%%
@@@@usage#Usage
more(x) displays object x using a 'paging' program that displays a
screenful at a time.  On Unix/Linux by default it uses Unix/Linux
program 'more'.  If variable PAGER exists and is a CHARACTER scalar,
then it is assumed to specify a paging program.  For example, on some
Unix/Linux systems, if the value of PAGER is "less -x4", then more()
invokes Unix/Linux program 'less' with tab stops set every 4 positions.

By default, when x is a macro, more(x) displays it after stripping off
'$$' from temporary variable names.  Use more(x,stripdol:F) To see the
actual '$$' in the macro.

When x is REAL, you may use any of keywords 'nsig', 'format', and
'missing' as on print(), but not 'name' and 'file'.

The lines written to the screen are not written to a spool file, nor are
they redisplayed after a plot.  See spool().

More is implemented as a pre-defined macro and is not available in all
versions of MacAnova.
@@@@______

====Mouse()#plotting
%%%%
Str <- Mouse([getpoints:T or getlines:T or getbox:T] [,xyonly:T or n:N]\
  [,cancelok:T] [graphics keyword phrases]), positive integer N <= 20
%%%%
@@@@introduction#Introduction
Mouse() provides a way to get x-y coordinates from a graphics window so
that you can add points, lines, boxes or character information at points
whose x- and y-coordinates are chosen interactively.

Mouse() is implemented only in windowed versions and on Unix/Linux
versions implementing Tektronix 4014 emulation.  (Of course, it cannot
workout a Tektronix terminal emulator that allows graphical input (GIN)
mode.)

In a Unix/Linux version with Tektronix emulation, Mouse() automatically
activates the graphics screen.  In windowed versions, you have to select
the graphics window where you want to get x-y coordinates.  In some
versions, pressing 'q' at any time before the operation is finished
aborts Mouse() and pressing 'r' restarts it, forgetting any coordinates
already selected.

@@@@usage#Usage
The basic usages of Mouse() are as follows
    Usage                                      Returns
  Str <- Mouse([xyonly:T])                   x-y coordinates of 1 point
  Str <- Mouse(getpoints:T [,xyonly:T])      x-y coordinates of 1 point
  Str <- Mouse(getpoints:T, n:N [,xyonly:T]) x-y coordinates of N points
  Str <- Mouse(getlines:T [,xyonly:T])       2 endpoints of a line
  Str <- Mouse(getlines:T, n:N [,xyonly:T])  N+1 points defining seg-
                                             mented line
  Str <- Mouse(getbox:T [,xyonly:T])         x-y coordinates of the cor-
                                             ners of a rectangular box,
                                             plus the first corner
                                             repeated.
N must be an integer between 1 and 20.

With each of these usages, you can also use keyword phrase 'cancelok:T';
without 'cancelok:T', cancelling Mouse() by pressing 'q' is considered
an error; with 'cancelok:T', pressing 'q' causes Mouse() immediately to
return NULL.

@@@@result#Result
After you select one or more positions in graphics window I, Str becomes
a structure whose first two components, 'x' and 'y', are REAL scalars or
vectors containing the x- and y-coordinates being returned.

With keyword phrase 'xyonly:T', 'x' and 'y' are the only components.
Otherwise the structure also has component 'window' with integer value
I, and component 'add', a LOGICAL scalar with value True.  With
getlines:T and getbox:T, 'lines' is an additional LOGICAL scalar
component having value True.

@@@@graphics_keyword_use#Graphics keyword use
When 'xyonly:T' is not an argument, you can include additional "extra"
keyword phrases, usually graphics keyword phrases, after the Mouse()
keyword phrases just described.  These will be made part of the output
structure.  For example, Mouse(getbox:T,linetype:2,thickness:3) returns
structure(x:xcoord, y:ycoord, window:I, add:T,lines:T, linetype:2,
thickness:3).  If keyword 'add' is among these "extra" keywords, Mouse()
does not include its own component 'add' in the structure returned, and
similarly for keywords 'lines' and 'window'.  For example,

  Cmd> Str <- Mouse(getlines:T, symbols:"\1",add:F, lines:F)

sets Str to structure(x:xcoord, y:ycoord, window:I, symbols:"\1", add:F,
lines:F).

@@@@comparison_of_versions#Comparison of versions
Using Mouse() differs slightly among different versions.  On windowed
versions you select positions by clicking and releasing the mouse button
with the cursor or pointer in a graphics window.  In a version running
under Xterm on a Unix/Linux workstation, you need to press Enter or
Return after releasing the mouse button.  On other Tektronix terminal
emulators pressing the mouse button may be sufficient.  On some
emulators, it may not work at all.

The action of Mouse() starts when you click and release the mouse with
the cursor or pointer in a graphics window.  The action then taken
depends on whether 'getpoints:T', 'getlines:T' or 'getbox:T' is an
argument to Mouse() (default is 'getpoints:T').  The action ends when
you depress and release the button the final time.  In the windowed
versions, Mouse() draws temporary lines as you move the mouse in the
window, erasing them before it returns.

In windowed versions, at any time before the final click you can restart
selection of locations by moving the cursor outside the window.
Temporary lines or marks are erased and you can select a different
window if you want.

In windowed versions, you can interrupt and terminate the action at any
time by selecting Interrupt on the File menu or pressing Ctrl+I
(Command+I on Macintosh).  In unwindowed versions, pressing the
interrupt key (usually Ctrl-C) terminates the action.

@@@@getpoints_keyword#Keyword 'getpoints'
Mouse(getpoints:T [,n:N] ...) and Mouse([n:N] ...).
 As you move the mouse, cross hairs (horizontal and vertical lines)
 appear and follow the cursor until you click and release at which time
 the point selected is marked temporarily.  When N > 1, the cross hairs
 appear again until you click and release to mark the next point.  This
 continues for N points.  After the final click, Mouse() erases the
 marked points and returns structure(x:xcoord, y:ycoord, window:I,
 add:T) where xcoord and ycoord are the x- and y-coordinates of the
 point or points selected.

 Mouse(getpoints:T,xyonly:T [,n:N]) or Mouse(xyonly:T [,n:N]) returns
 only structure(x:xcoord, y:ycoord).

@@@@getlines_keyword#Keyword 'getlines'
Mouse(getlines:T [,n:N])
 As you move the mouse until you click and release it again, a contin-
 uously updated line is drawn between the current position of the mouse
 and the first location clicked.  When N > 1, another continuously
 updated line is drawn between the current position and the second
 location selected, and so on until N connected line segments have been
 drawn.  After the final click and release, Mouse() erases the lines
 drawn and returns structure(x:xcoord, y:ycoord, window:I, add:T,
 lines:T) where xcoord and ycoord contain the x- and y-coordinates of
 the N+1 points defining the segmented line.

 Mouse(getlines:T,xyonly:T [,n:N]) returns only structure(x:xcoord,
 y:ycoord).

 If you press the shift key while tracing a line, the line being drawn
 if forced to be either horizontal or vertical.

@@@@getbox_keyword#Keyword 'getbox'
Mouse(getbox:T)
 As you move the mouse, a continuously updated rectangular box is drawn.
 One corner is at the first position clicked on and the opposite corner
 is the current position.  After a second and final click and release,
 Mouse() returns structure(x:vector(x1,x1,x2,x2,x1), y:vector(y1, y2,
 y2,y1,y1),window:I, add:T,lines:T), where (x1,y1) is the initial
 position clicked on and (x2,y2) is the final position of the opposite
 corner.  Note that the initial position is repeated as the last point
 and that the points trace out the entire border of the box.  Keyword
 phrase 'n:N' is illegal with 'getbox:T'.

 Mouse(getbox:T,xyonly:T) returns only
   structure(x:vector(x1,x1,x2,x2,x1),y:vector(y1,y2,y2,y1,y1))

 If you press the shift key while moving the mouse, the rectangle drawn
 is forced to be square (not in Tektronix emulation).

The form of the output from Mouse() is designed to make it easy inter-
actively to add information to a plot, either using one of the graphics
commands (see topic 'graphs') or assignment to GRAPHWINDOWS (see topic
'graph_assign').

@@@@examples#Examples
                                Examples
  Cmd> s <- Mouse(getpoints:T, symbols:"*") # or s <- Mouse(symbols:"*")

  Cmd> GRAPHWINDOWS[s$window] <- s

This plots "*" at the position selected with the cross hairs.  The
second command can be replaced by addpoints(GRAPHWINDOWS[s$window],
keys:s).

  Cmd> s <- Mouse(getlines:T, linetype:2); GRAPHWINDOWS[s$window] <- s

This draws in the window the line determined by two click and releases
of the mouse in a graphics window.

  Cmd> s <- Mouse(getbox:T); GRAPHWINDOWS[s$window] <- s

This draws in the window the box determined by the mouse positions.

@@@@use_with_GRAPHWINDOWS#Use with GRAPHWINDOWS
If you know the window you will draw into, say window 1, you can plot a
point, line or box simply by GRAPHWINDOWS[1] <- Mouse(KEY:T ...), where
KEY is 'getpoint', 'getline' or 'getbox':

  Cmd> s <- Mouse(getlines:T, n:5, linetype:2,thickness:3)

  Cmd> addlines(GRAPHWINDOWS[s$window], keys:s)

This draws 5 connected line segments with line type 2 and thickness 3.

  Cmd> s <- Mouse(getlines:T, show:F)

  Cmd> addlines(GRAPHWINDOWS[s[3]], keys:s[-3])

  Cmd> addstrings(s$x[1],s$y[1], "Interesting feature",\
       window:s$window, justify:"l")

This draws the line and then draws "Interesting feature" at the first
position clicked on.  Component 'window' is omitted in addlines() (by
using s[-3] as an argument) because 'window:n' can't be used with
'show:F'.

@@@@see_also#Cross references
See also 'structures', strconcat(), addlines(), addstrings().
@@@@______

====movavg()#time series
%%%%
movavg(Theta,A [,reverse:T, limits:vector(i1 [,i2]), start:startVals,\
  seasonal:L]), REAL vector or NULL Theta, REAL vector or matrix A, REAL
  startVals the same size and shape as A, positive integer L
%%%%
@@@@introduction#Introduction
movavg() is designed to implement a moving average operator as the term
is used in ARIMA time series analysis.  For a more ordinary moving
average, convolve() is preferable.  movavg() can also be used to compute
differences of a series or, together with autoreg(), to find the power
series coefficients of rational functions.

@@@@usage#Usage
movavg(Theta,A) applies the moving average operators specified by the
columns of the REAL matrix Theta to the columns of the REAL matrix A.
If ncols(Theta) = 1, Theta is applied to every column of A and if
ncols(A) = 1, each column of Theta is applied to A.  The result is a
matrix with nrows(A) rows and max(ncols(Theta), ncols(A)) columns.  If
both Theta and A have more than one column, they must both have the same
number of columns.

Specifically, assuming for simplicity that both Theta and A are vectors
so that the result x is a vector, then
    x[i] = A[i] - sum(Theta[k]*A[i-k],1<=k<=nrows(theta)),
with A[l] taken to be 0 for l < 1.

When Theta is a vector, movavg(Theta,A) can be expressed in matrix terms
as Theta1 %*% A, where Theta1 is a nrows(A) by nrows(A) matrix.  For
example, when nrows(Theta) = 2,
         [   1          0        0       0   ...    0        0       0 ]
         [-Theta[1]     1        0       0   ...    0        0       0 ]
Theta1 = [-Theta[2] -Theta[1]    1       0   ...    0        0       0 ]
         [   0      -Theta[2] -Theta[1]  1   ...    0        0       0 ]
         [ ........................................................... ]
         [   0          0        0       0   ... -Theta[2] -Theta[1] 1 ]

NOTE: The sign assumed for Theta is not affected by variable MASIGN
which is recognized by several macros in file Arima.mac.  Type
arimahelp(MASIGN) for details.

If Theta is NULL, the result is the same as A, stripped of labels or
notes, if any.  Also, the result is a true vector or matrix (ndims = 1
or 2).

@@@@first_and_higher_differences#First and higher differences
A common usage is movavg(1,A), where A is a vector or matrix.  This
computes the first differences A[1,] - 0,A[2,]-A[1,], ...,A[n,]-A[n-1,].
Second differences can be computed by movavg(vector(2,-1),A), third
differences by movavg(vector(3, -3, 1), A), and so on.

@@@@reverse_and_seasonal_keywords#Keywords 'reverse' and 'seasonal'
movavg(Theta,A,reverse:T) applies the moving average operator in
reverse:
    x[i] = A[i] - sum(Theta[k]*A[i+k],1<=k<=nrows(phi))
with A[l] = 0 for l > nrows(A).

movavg(Theta,A,seasonal:L [,reverse:T) does the same, except that the
computations are of the forms
    x[i] = A[i] - sum(Theta[k]*A[i-k*L],1<=k<=nrows(Theta)).

@@@@limits_and_start_keywords#Keywords 'limits' and 'start'
movavg(Theta,A,limits:vector(i1,i2),start:StartVals [,reverse:T,
seasonal:L]) is the same except that x[i] is computed as just described
only for i1 <= i <= i2, with the remaining values copied from rows 1 to
i1-1 and rows i2+1 to nrows(A) of matrix StartVals.

The value for limits can also be a scalar j between 1 and nrows(A).  In
this case, with reverse:T, i1 = 1, i2 = j, and without reverse:T, i1 =
j, i2 = nrows(A).

StartVals must have the same number of columns as A and usually has the
same number of rows.  When nrows(StartVCals) != nrows(A), without
reverse:T, i2 must be nrows(A) and with reverse:T, i1 must be 1.  In
this case, the elements of StartVals are copied to the rows not included
between i1 and i2 and hence nrows(start) must match nrows(A) - (i2 - i1
+ 1).

Unlike what happens with autoreg(), the values computed for rows i1 to
i2 are unaffected by the values of StartVals.

@@@@examples#Examples
Examples (theta and theta1 vectors of same length):
  Cmd> m <- nrows(theta); n <- 300
  Cmd> movavg(theta,rnorm(n+m))[-run(m)]
     generates a moving average series with normal innovations.
  Cmd> movavg(theta,matrix(rnorm(10*(n+m),10))[-run(m),]
     generates 10 independent moving average series
  Cmd> movavg(hconcat(theta,theta1),rnorm(n+m))[-run(m)]
     generates two moving average series with the same innovations
  Cmd> movavg(.3,movavg(-.1,rnorm(230),seasonal:4))[-run(30)] generates
      a (0,0,1)x(0,0,1)-4 seasonal ARMA time series

@@@@relationship_with_autoreg#Relationship with autoreg()
movavg() is the inverse of autoreg() and vice versa, in that
   movavg(phi,autoreg(phi,x))   and   autoreg(phi,movavg(phi,x))
both reproduce x, except for rounding error.

@@@@see_also#Cross references
See also autoreg().
@@@@______

====mulvarhelp()#general,multivariate analysis
%%%%
mulvarhelp(topic1 [, topic2 ...] [,usage:T] [,scrollback:T])
mulvarhelp(topic, subtopic:Subtopics), CHARACTER scalar or vector
  Subtopics
mulvarhelp(topic1:Subtopics1 [,topic2:Subtopics2 ...])
mulvarhelp(key:Key), CHARACTER scalar Key
mulvarhelp(index:T [,scrollback:T])
%%%%
@@@@usage#Usage
mulvarhelp(Topic1 [, Topic2, ...]) prints help on topics Topic1, Topic2,
... related to macros in file mulvar.mac.  The help is taken from file
mulvar.mac.

mulvarhelp(Topic1 [, Topic2, ...] , usage:T) prints usage information
related to these macros.

mulvarhelp(index:T) or simply mulvarhelp() prints an index of the topics
available using mulvarhelp().  Alternatively, help(index:"mulvar") does
the same thing.

mulvarhelp(Topic, subtopic:Subtopic), where Subtopic is a CHARACTER
scalar or vector, prints subtopics of topic Topic.  With subtopic:"?", a
list of subtopics is printed.

mulvarhelp(Topic1:Subtopics1 [,Topic2:Subtopics2], ...), where
Suptopics1 and Subtopics2 are CHARACTER scalars or vectors, prints the
specified subtopics.  You can't use any other keywords with this usage.

In all the first 4 of these usages, you can also include help() keyword
phrase 'scrollback:T' as an argument to mulvarhelp().  In windowed
versions, this directs the output/command window will be automatically
scrolled back to the start of the help output.

@@@@key_keyword#Keyword 'key'
mulvarhelp(key:key) where key is a quoted string or CHARACTER scalar
lists all topics cross referenced under Key.  mulvarhelp(key:"?") prints
a list of available cross reference keys for topics in the file.
@@@@______

mulvarhelp() is implemented as a predefined macro.

@@@@see_also#Cross references
See help() for information on direct use of help() to retrieve
information from mulvar.mac.
@@@@______

====nameof()#variables,character variables
%%%%
nameof(var1, var2, ... )
%%%%
@@@@usage_and_example#Usage and example
nameof(arg1, arg2, ..., argk) returns a CHARACTER vector containing the
names of the arguments.  If an argument is the result of a computation
or is a quoted string, its name will be descriptive.

If an argument is missing, the name returned is "".

Example:
  Cmd> nameof(x,cos,17,3+5,vector(x),matrix(run(10),5),,"Hello")
  (1) "x"
  (2) "cos"
  (3) "NUMBER"
  (4) "NUMBER"
  (5) "VECTOR"
  (6) "MATRIX"
  (7) ""
  (8) "STRING"

@@@@see_also#Cross references
See also compnames(), isname(), typeof(), varnames(), rename()
@@@@______

====nbits()#operations,transformations,glm
%%%%
nbits(x), where x consists of 1 or more integers between 0 and
  4294967295
%%%%
@@@@usage#Usage
nbits(x), where x is an integer with value between 0 and 4294967295
(2^32-1), computes the number of non-zero bits in the binary
representation of x.  For example, nbits(123455) is 11 since 123455 has
binary representation 00000000000000011110001000111111b.

If x is not an integer or x < 0 or x > 4294967295, a warning message is
printed and the result is set to MISSING.

If x is a REAL vector, matrix or array or a structure all of whose
components are REAL, nbits(x) is a variable or structure of the same
size and shape as x, each element of which is the number of bits in the
corresponding element of x.

nbits() is useful with the output of modelinfo(bitmodel:T).

@@@@examples#Examples
Examples:
After anova("y=(a+b)^2 + ((a+b)^2).x",silent:T) the following commands
compute the number of variables or variates in term 5 and in all terms:

  Cmd> nvars5 <- sum(vector(nbits(modelinfo(bitmodel:T)[5,]))); nvars5
  (1)           2

  Cmd> vector(sum(nbits(modelinfo(bitmodel:T)')),labels:TERMNAMES[-8])
    CONSTANT           a           b         a.b         a.x         b.x
       a.b.x
           0           1           1           2           2           2
           3

@@@@see_also#Cross references
See also topics 'bit_ops', modelinfo().
@@@@______

====ncols()#variables
%%%%
ncols(x) where x is a matrix or generalized matrix
%%%%
@@@@usage_and_examples#Usage and examples
ncols(x) returns the number of columns of matrix argument x.  If x has
more than two dimensions, no more than two dimensions may exceed 1 and
it is treated as described in topic 'matrices'.

If x is a structure, ncols(x) is a structure.  If xi is the i-th
component of x, the i-th component of ncols(x) is ncols(xi).

@@@@examples#Examples
  Cmd> x <- run(7); vector(nrows(x),ncols(x),nrows(x'),ncols(x'))
  (1)           7           1           1           7

  Cmd> y <- array(run(24),1,6,1,4);vector(nrows(y),ncols(y))
  (1)           6           4

  Cmd> ncols(structure(x,y))
  component: x
  (1)           1
  component: y
  (1)           4

@@@@see_also#Cross references
See also topics nrows(), dim(), ndims(), length(), 'structures'.
@@@@______

====ncomps()#variables,structures
%%%%
ncomps(Str) where Str is a structure
%%%%
@@@@usage_and_example#Usage and example
ncomps(Str) returns the number of components in structure Str.  It is an
error if Str is not a structure.

Example:
  Cmd> ncomps(describe(run(10))) # describe has structure result
  (1)           8

@@@@see_also#Cross references
See also topics ndims(), dim(), length(), isstruc(), describe(),
'structures'.
@@@@______

====ndims()#variables,null variables
%%%%
ndims(x)
%%%%
@@@@usage#Usage
ndims(x) computes the number of dimensions of x.  If x is a vector,
ndims(x) is 1; if x is a matrix, ndims(x) is 2, even if has column
dimension 1.

If x is a NULL variable, ndims(x) is 0.

If x is a structure, ndims(x) is a structure.  If x_i is the i-th
component of x, the i-th component of ndims(x) is ndims(x_i).

@@@@examples#Examples
Examples:
  Cmd> x <- run(7); vector(ndims(x),ndims(x'), ndims(x''))
  (1)           1           2           2

  Cmd> y <- array(run(24),1,6,1,4); ndims(y)
  (1)           4

  Cmd> ndims(structure(x,y))
  component: x
  (1)           1
  component: y
  (1)           4

@@@@see_also#Cross references
See also topics length(), dim(), 'NULL'.
@@@@______

====news*#general
%%%%
help(news) or help(news:yymmdd1) or help(news:vector(yymmdd1,yymmdd2)),
  where yymmdd1 and yymmdd2 are integers like 990416 and 19990416
  (April 16, 1999) or 030416 and 20030416 (April 16, 2003)
%%%%
@@@@2004-November
041115 Bug fix so that expr[[1]] works when expr is a non-structure
expression like run(5) or dmat(psi0).

@@@@2004-October
041025 Minor modification to coefs() and secoefs() that might be
considered a bug fix.  In a term which includes an interaction of one or
more factors with a variate, no dimension is allocated to the variate in
the array of coefficients or standard errors.  Previously, it was
allocated a dimension of length 1.

041005 Bug fixed in tabs() that manifested itself with multivariate data
with at least one factor with a MISSING factor level.

@@@@2004-january
040129 Minor bug fix to run(start,end,inc) and for(i,start,end,inc){...}
to ensure that the final value will be end when end-start is intended to
be an exact multple of inc.  It sometimes wasn't when |end - start| was
small compared to max(|start|,|end|).

040115 array() now accepts a scalar argument 1 which fills the entire
output array.  Thus, for example, array("Q",2,3,4) is equivalent to
array(rep("Q",24),2,3,4).

@@@@2003_december
031216 Fixed minor bug; setoptions(maxwhile:N) didn't take hold
immediately.

031214 Fixed serious memory leak occuring during Str$a <- b

031211 Fixed bug that caused a crash with modelinfo(aliased:T) after
anova() with a balanced model.  Fixed warning messages when reading
CHARACTER variables with matread() and read().

@@@@2003_november
031107 Fixed bug in save() and restore() that failed to restore custom
ticks on graphs encoded in GRAPH variables.

031105 Fixed bug that caused crash on Str$c[i] when Str had no component
'c'.

@@@@2003_september
030924 print() and write() now recognize keyword phrase 'notes:T'
enabling printing of any notes attached to variables being printed.

030904 Fixed bug so that list(factors:T) and listbrief(factors:T) no
longer cause a crash.

@@@@2003_july
030711 New function lowess() for doing local linear smoothing using the
LOWESS algorithm.

Many subtopics now have an associated title which is printed in help
output.

@@@@2003_may
030522 New match() and unique() keyword phrase relative:T uses relative
error in inexact comparisons.

030519 Moved news items earlier than 1 January 2001 to file macanova.nws.

030517 New function equal() to compare two variables of any type except
GRAPH for equality or approximate equality.

030515 New functions typeof() and shapeof() to return the type or shape
of of one or more variables.

030503 New keyword phrase 'badoptok:T' on setoptions() and getoptions()
directs that a reference to an illegal option is not an error.

@@@@2003_march
030321 New macros printoptions() (prints option values in concise
format) and restorenames() (restores variables saved by restore() in
structure SAVEDNAMES).

030320 levmar() and related macros moved from file arima.mac to math.mac.

nlreg() and related macros moved from file arima.mac to regress.mac.

030318 New macros for working with complex matrices have been added to
file math.mac.  These include cdiag(), ceigen(), cjtranspose(),
cmatmultc(), csolve(), csubscr(), ctrace(), and ctranspose().

030317 Either argument to cprdc(), cprdcj(), cdivc() and cdivcj() may
have 1 row which is implicitly duplicated to match the number of rows of
the other argument.  In particular, cdivc(1,z) computes the complex
reciprocal of z and cdivc(cmplx(a,b),z), where a and b are scalars,
multiplies z by a + b*i.

030315 New functions cdivc(), cdivcj(), hdivh() and hdivhj() for
implementing cx1/cx2, cx1/cconj(cx2), hx1/hx2, and hx1/hconj(hx2) for
fully complex and packed Hermitian complex series.

030311 You can use keyword 'symbols' to specify symbols for plotting
outliers on boxplot() and vboxplot().

@@@@2003_february
030220 New usage tsplot(y,time [,keyword phrases]) allows time series
plots vs non-equally spaced time points.

030217 Changed default tick marks with 'logx:T' and/or 'logy:T so they
are less dense when max/min > 1e10.

030208 list() output now indicates which variables have labels and/or
notes.  You can use keyword phrases 'labeled:T' and/or 'notes:T' to
limit variables listed to those with labels and or notes.

@@@@2003_january
030115 MacAnova 4.13 Release 1.

030113 New keyword phrase 'sort:F' on readdata() and clipreaddata()
suppresses sorting of factor values in alphabetical order when there is
one or more non-numerical column.

addmacrofile(), addhelpfile() and adddatapath() correctly handle file
and path names names of the form "" in windowed versions.

New macro facanal() in Mulvar.mac for doing factor analysis using ULS,
GLS or ML estimation methods, including optional rotation of loadings.

New macros hotellval() and hotell2val() in Mulvar.mac for computing one-
and two-sample Hotelling's T^2 statistics and associated P-values.

Macro standardize() in Mulvar.mac to standardize vector or matrix of
data.

In Mulvar.mac, macro mvngen() for generating mulivariate normal samples
has been renamed rmvnorm().

@@@@2002_october
021022 New macro buildfactor() in file design.mac makes it easier to
construct factors for balanced factorial designs in regular order (first
subscript changing fastest, last slowest).

021015 Macro makecols() enhanced.  By default, it prints a list of
variables created.  Keyword phrase factors:TorFvec allows you to specify
which vectors should be turned into factors.  Keyword phrases quiet:T
and silent:T allow you to suppress its report and any warning messages.

021009 New argument lists for power() and power2(): power(noncen,ngrp,
nrep,alpha) and power2(noncen2,numdf,denomdf,alpha).  The previous order
in which alpha was argument 3 and nrep or denomdf was argument 4 is
still recognized but is deprecated.

@@@@2002_september
020915 New keyword phrase 'quiet:F' on solve() and rsolve() enables a
a warning message about singularity when singok:T is an argument.

It is now an error when overflow is detected in an computations by
det(), solve() or rsolve(), or operators %\% and %/%.

@@@@2002_august
020827 New macro formatpval() in file MacAnova.mac for formatting
P-values similarly to how GLM functions such as regress(), anova() and
logistic() do.

Fortran style double precision numbers like -3.14592654d3 and 4.15D-5
are now read as if the 'd' or 'D' were 'e'.

020819 New option 'enableitem' in Windows and Motif versions control
whether printing the command/output window or a graph window is allowed.

In the Windows and Motif versions, File Menu items Print Window and
Print Graph are disabled by default because they often (usually?) cause
MacAnova to crash.  They can be re-enabled using the new option
'enableitem'.  Type 'help(options:"enableitem")' for details.

020808 New option 'minpvalue' controls minimum P-value printed as
computed in GLM output (regress(), anova(), ...).  Smaller values are
printed just as "< 1e-8", for example.

020805 The algorithm used to compute central and non-central cumulative
and tail probabilities for the F and beta distributions has been
improved.  More significant digits are preserved when the desired
probability is very small.

@@@@2002_july
020712 You can now assign directly to components of components of
structures.  For example when Str is a structure with component a which
is also a structure with component b, Str$a$b <- x is legal as is
Str$a[[J]] <- x and Str[[i]][[J]] <- x.

You can no longer directly extract, either by name or number, a
structure component that is nested more than 31 deep (a$b$c$d$e is
nested 4 deep, example).  That is a$b$...$z is illegal if there are more
than 31 successive components named or specified by number.

020705 MacAnova now ignores any '_' characters in the mantissa of a
number (part before the exponent, if any).  Thus 123_456.789_1e3 is
equivalent to 123456.7891e3.

020702 When Str is a structure, Str$name <- x and Str[[J]] <- x are now
legal.  Str[[J]] <- x works the same as Str[J] <- x.

@@@@2002_may
020529 New functions digamma() and polygamma() for computing the digamma
function and its derivatives.

A slightly more accurate algorithm for lgamma() is used in some
versions.

020511 New keyword phrase 'upper:T' on all cumxxx() and invxxx()
functions directs an upper tail probability (cumxxx()) or upper
probability point (invxxx()) be computed.  Instead of 'upper:T' you can
use 'lower:F'.

020501 New describe() keyword phrase 'fivenum:T' computes min, q1,
median, q3 and max.

@@@@2002_april
020430 New sum(), prod(), max() and min() keywords 'dimensions',
'margins', 'squeeze and 'undefvals'.  These allow you to specify which
dimension or dimensions to operate over or not operate over, to reduce
unneeded dimensions of the result, and specify values to be returned
when all values to be operated on are MISSING.

@@@@2002_march
020225 Replacement of code implementing matrix multiplication (%*%, %c%,
%*%) by level 3 BLAS routine dgemm() speeds up operations with large
matrices as much as a factor of 15 on some systems.

020321 New functions pushmodel() and popmodel() allow temporary saving
and restoring of internal information about the current model.

@@@@2002_february
020225 Three new keyword phrases for boxplot().  'vs:predictor' allows
you to positions boxes according to values in REAL vector predictor.
'boxsize:W' allows control of the thickness of the boxes drawn.  And
'boxtype:m', where m > 0 is an integer, specifies the type of box
drawn.  m = 1 is the default; m = 2 means a simplied boxplot using only
the two extremes and the three quartiles.

@@@@2001_december
011217 New keyword phrase 'tolerance:tol' on swp() controls decision as
to whether a matrix is non-singular

011214 New locked pre-defined constant NA with value MISSING allows
usage like  y <- vector(3,2,NA,5,6).

New keyword phrase 'silent:T' on describe(), tabs() and split()
suppresses warning messages about MISSING values or overflow.

It is now an error in split(x,a) and tabs(x,a [,b ...])) for a factor
argument to have any levels >= 32768.

011205 Plugged minor memory leak on usages such as str[[1]], str$T,
str$F and str$NULL where str is a structure.

011201 Some changes to minimization macros bfs(), dfp(), broyden() and
neldermead() in file math.mac.  If you use these, you should check the
help information for these macros.

@@@@2001_november
011125 New keyword phrase 'kaiser:T' on rotation() to specify Kaiser
normalization.

011109 Fixed bugs in contour() and _Follow() in Graphics.mac.  They
caused contour() to fail to find certain contours.

@@@@2001_october
011029 New pre-defined macros writedata() (writes vector arguments
as columns in a file) and clipwritedat() (puts on clipboard vector
arguments as columns).

makefactor() modified so the default for a CHARACTER argument is to use
the values as labels on the created factor.

011026 nameof() now returns "" for an empty argument; previously this
was an error.  Also, when an argument is a keyword phrase, the name
returned is the keyword name.

New function getkeywords() is similar to nameof() except the only
elements in the result which are not "" are the names of keywords in the
argument list.

011017 Bug fix in macro initialization at startup.  Macros intended to
be both locked and out-of-line are marked as such instead of just as
out-of-line.

@@@@2001_september
010926 New function makesymbols() to make it easier to generate custom
plotting symbols.  For example, makesymbols(vector("diamond","square"),
medium:T) returns vector("\011","\013").

@@@@2001_august
010811 New option 'traceback' with value T or F (default).  When True,
an error in a macro called by another macro prints the chain of calling
macros.

010810 All arguments to macros and certain functions (anytrue(),
alltrue(), gethelp(), getusage()) are now checked for correct matching
of '{' by '}', '[' by ']' and '(' by ')' before the macro or function is
executed.

010803 New spool() keyword phrase everything:T, forces spooling output
lines to a file even when printing to screen is suspended because option
'quiet' is True.

010802 Most macro names in the help files now have '()' appended just as
function names always have.  This makes it easier to tell when a
reference is to something that can be run.

New option 'quiet' allows suppression of all output except error
messages.

@@@@2001_july
010727 Variables can now be locked so they can't be deleted or changed.
See lockvars(), unlockvars() and delete().

Pre-defined numerical constants such as PI and E are now locked
variables.  To delete them, use delete(...,lockedok:T).

010725 resvsrankits(), resvsindex(), resvsyhat() now differ only in
their names.  They are now merely front ends to a new invisible macro
_resvsxxxx().

getfilename() should now work properly in Windows and Motif versions.

010723 Several changes in resvsindex(), resvsrankits() and resvsyhat().

The default plotting symbol is now a drawn asterisk ("\6") instead of a
printed asterisk ("*").  You specify a different plotting symbol using
keyword 'symbols' just as on other plotting commands and macros.

Keyword phrase standres:F suppresses standardization.

Keyword phrase usehii:T or usehii:F affects the way standardization is
done.

resvsindex() and resvsrankits() (but not resvsyhat()) work after an
ARIMA time series fit using macro arima().

Default labels and titles have been modified.

Help for resvsindex(), resvsrankits(), resvsyhat(), regs(), resid() and
yhat() is now only in file regress.mac.

010720 Fixed bug in model parser that omitted a term of the form {xyz}
if there was an earlier term of the form {xyzabc}, for example,
"y = {log(x)^2)} + {log(x)}".

010709 On plotting commands, symbols:"###" means use plotting symbols
"1", "2", ... .

010706 delete(x,return:F) is now legal.

010703 New keyword phrase index:"name" to print get an annotated index
of the topics in a help file.  New pre-defined variable HELPINDICES
contains the index topic names in the standard help files.

Macro addhelpfile() has been enhanced to update HELPINDICES as well as
HELPFILES.

New help topic macanova_index provides explicit commands to find help
topics using help keys.

New match() keyword phrase 'ignorecase:T'.

@@@@2001_june
010620 More changes in help related commands and macros.

help() and usage() start the search with the current help file if it is
one of the files named in HELPFILES.

gethelp() and getusage() keyword phrase 'printname:T' directs that the
file where help is found be identified.

Using 'all:T' with help() and usage() forces search of all files named
in HELPFILES.  It implies printname:T.

When a wild card pattern matches only one topic name, only the name
matched is printed, not the help information.

010619 Function help() has been renamed gethelp() and new macro
gethelp() has been renamed help().  This means that help(topic)
automatically searches all the help files in CHARACTER vector HELPFILES
for help on topic.  For most usages, the change should not be noticed.
Special help macros arimahelp(), designhelp(), graphicshelp(),
mathhelp(), mulvarhelp(), regresshelp(), and tserhelp() are no longer
necessary, but may be faster than help() since only one file is
searched.

match() modified.  When argument 1 is a vector and argument 2 is a
matrix or higher order array, match() compares argument 1 with each
column of argument 2 separately.

Version number bumped to 4.12.

010618 New keyword phrase help:T on getfilename() enables retrieval of
the name of the current help file.

New pre-defined macro gethelp() is used almost identically to help()
except it searches for help in all the help files in CHARACTER vector
HELPFILES.  At startup, HELPFILES is initialized to a list of the
standard help files, starting with macanova.hlp.

New pre-defined macro addhelpfile() adds a file name to the beginning or
end of HELPFILES.

010615 Quartimax, equimax and orthomax factor rotation methods
implemented in rotation() (method:"quartimax"; method:"equimax"; and
method:"orthomax",lambda:lam).

010614 New keyword phrase zero:zeroVal on print() and error().
CHARACTER scalar zeroVal is printed in place of zero.

010613 help() and usage() now return an "invisible" LOGICAL scalar whose
value is True only when at least one help topic was found.

New help() keyword phrase 'silent:T' suppresses warning messages.

macrousage() now returns an "invisible" LOGICAL scalar whose value is
True only when at least one macro was found.  Also, the elements of any
CHARACTER argument (not just the first) are presumed to be names of
macros.

010611 Changes made to the Windows version to recognize symbols produced
by Alt Gr key combinations on non-US keyboards.  They should be
recognized by default.  If this causes problems, the behavior can be
modified by new option 'keyboard'.  Type 'help(options:"keyboard")' for
details.

@@@@2001_may
010528 Many internal changes in the Macintosh verions, in prepration for
carbonization.  We hope none is noticable.

010516 New keyword phrases stripat:T and stripbrack:T on varnames().

010515 rotate() and reverse() now work with CHARACTER first argument.

010513 modelinfo(termnames:T) returns full term names, including the
'@' starting temporary variable names.

010509 delete(STRMODEL) now also clears the internal private information
about the latest GLM model fit.

010508 varnames(Model) now checks the model for correctness and handles
variables to be evaluated on-the-fly correctly.  In particular, the
names of on-the-fly variables include starting '{' and ending '}'.

010503 New function isnumber() to check whether CHARACTER scalars
represent non-MISSING numbers.

@@@@2001_april
010412 New keyword phrases 'file:T' and 'path:T' on isname() allow
testing whether a name is a legal file or path name.

010411 Changes to restore() to ease using with workspace files saved by
save() or asciisave() on another computer: Variables HOME, DATAFILE,
DATAPATHS and MACROFILES are restored only if they do not currently
exist.  Any that are not restored are gathered in structure SAVEDNAMES
with components HOME, DATAFILE, DATAPATHS and/or MACROFILES.

010403 ismissing(), rank() and, when 'n:N' is not an argument, rankits()
and halfnorm() now preserve the labels of their arguments.  sort() and
grade() do not preserve labels.

A number of functions that operate on the components of structure
arguments now propagate component labels from their arguments to their
result.  These include sum(), prod(), max(), min() and transformations
such as sqrt(), log() and cos().

@@@@2001_march
010324 The name of the file read by vecread(), read(), matread(),
macroread(), inforead() and read() is now printed by default.  This can
be suppressed by 'printname:F' or 'silent:T'.

Macro getmacros() updated to be aware of 'printname' keyword on
getmacros() and to use getfilename(last:T) to get a file name to print.

010322 getfilename(last:T [, nameonly:T or pathonly:T]) returns the name
of the most recently opened file.

010308 Fixed bug that occurred in <<"macroName">>(args), when macro
macroName() was not defined.  Now external macro files are searched.

@@@@2001_february
010222 Fixed bug in glmfit() with dist:"binom".

010213 New keyword phrase 'options:F' on restore() suppresses
restoration of any options values saved in the workspace file.

On windowed versions, when restoring a workspace saved on an
incompatible system, restore() never restores option 'matchdelay'.  This
gets around a timing problem arising because different time units are
used for this option on different systems.

010210 Fixed bug in keyvalue() with keyword 'default' when Properties is
"macro" or "graph" and the keyword list is empty.

010207 Fixed bug in readdata() which resulted in a 'line longer than
2000 characters' error message.

010201 New function getfilename() for windowed versions to allow you to
select interactively a file name or folder name to be returned as a
CHARACTER scalar.  addmacrofile(getfilename()) and
adddatapath(getfilename(pathonly:T)) are among the ways you can use
getfilename().

@@@@2001_january
010124 Case is ignored in describe() keywords.  This may be the start of
a movement toward case in keyword recognition generally.

New describe() keyword phrase excludeM:T directs that the median is
excluded from the upper and lower halves of the data when computing
quartiles.  This also is recognized by stemleaf(), boxplot(), and
vboxplot() as well as boxplot5num() in graphics.mac

010114 Fixed bug so that typing just 'help' or 'Help' gets something
meaningful.

010110 Added statistics 'iqr' (interquartile range) and 'range' (max -
min) to describe().

010108 Fixed bug in Fourier transforms whose length has 20 or more prime
factors, but found another.  Current transforms crash if the
product of unpaired factors is too large.  A check has been added to
prevent this from happening.

010104 Many minor changes to some of the macros in arima.mac and
tser.mac.  In particular, the choice of the number, Nfreq, of
frequencies used in Fourier transforms has been regularized.
  When you specify Nfreq in the list of arguments, it is always an error
  if Nfreq has a prime factor > 29.

  Variable S is used only for macros such as compfa and specarma which
  return a frequency function.  When used, it is an error if S has any
  prime factor > 29.

  In other situations, when a default value is computed, the computed
  value is increased to the next integer having no prime factor > 29,
  for example goodfactors(2*nrows(y)).

Macros ffplot() and tsplot() in tser.mac now look for CHARACTER scalar
TIMEUNIT to create default labels and titles.  If you have monthly data
and want labels in terms of years, you would set DELTAT <- 1/12 and
TIMEUNIT <- "year".

There are now 'news' arimahelp() and tserhelp() topics.  Type, for
example, arimahelp(news) or arimahelp(news:vector(001201,010115).

Many arimahelp() and tserhelp() articles have been updated.

====next#control,syntax
%%%%
for(i,run(n)){if(x[i] < 0){next} .... }
for(i,run(n)){for(j,run(m)){if(x[i,j] < 0){next 2} .... }}
%%%%
@@@@usage#Usage
'next', when used in a 'while' or 'for' loop, skips to just before the
'}' that terminates the loop, ignoring any intervening commands.
Execution resumes immediately before the '}'.

'next n', where n is a positive integer, skips to the end of the n-th
enclosing loop.  For example, 'next 1' is equivalent to 'next' and will
skip to the end of the current loop; 'next 2' will exit the current loop
and skip to the end of the loop enclosing it; and so on.  n must be a
literal integer ('1', '2', ...) and not a variable with integer value.

It is an error to use 'next' outside of a loop or to use 'next n' when
not enclosed in at least n loops.

@@@@in_a_macro_or_evaluated_string#In a macro or evaluated string
In an evaluated string or out-of-line macro, 'next' can be used only to
skip to the end of a loop that started in the macro or evaluated string.
It is an error to try to skip to the end of a loop that started outside
the macro or evaluated string.  See evaluate() and 'macros'.

Using 'next' in an in-line macro to skip to the end a loop that started
outside the macro will work, but is a bad programming practice.

@@@@examples#Examples
Examples:
  for(i,run(100)){... compute x ...;if(x<0){next};... do something ...;}
Whenever the computed x becomes negative, no further computation is done
for that value of i.

  for(i,run(10)){for(j,run(5)){...;if(x<0){next 2}; ... }; ...}
Whenever x becomes negative on any pass through the j loop, that loop is
terminated and execution resumes before the '}' which ends the i loop.

@@@@see_also#Cross references
See also topics 'if', 'for', 'while', 'break', 'breakall', batch().
@@@@______

====notes#general,macros,variables
%%%%
This topic has information on" notes" attached to variables.
Functions for working with such notes are:
  attachnotes(x, Notes) # attach Notes to x
  attachnotes(x, NULL)  # remove notes from x
  notes <- getnotes(x)  # retrieve notes from x
  if (hasnotes(x)){...do something with notes...}
  y <- vector(x, notes:Notes) # create vector with notes Notes
  y <- matrix(x, notes:Notes) # create matrix with notes Notes
  y <- array(x, notes:Notes)  # create array with notes Notes
  plot(x,y [,... ],notes:Notes)     # Notes attached to LASTPLOT
  chplot(x,y,symbols:ch [,...],notes:Notes) # Notes attached to LASTPLOT
  lineplot(x,y [,...], notes:Notes) # Notes attached to LASTPLOT
  showplot([...,] notes:Notes)      # Notes attached to LASTPLOT
%%%%
@@@@using_notes_on_variables#Using notes on variables
You can attach CHARACTER vectors as "notes" to almost any variable,
including GRAPH variables and macros.  These can be used to record
descriptions of data or plots or usage notes for macros.

When x is an existing variable

  Cmd> attachnotes(x, vector("Heights of Stat 1001 students",\
     "collected Fall 1997"))

attaches the descriptions to variable x.

You can append additional notes to a variable using appendnotes():

  Cmd> appendnotes(x, "There were 29 women and 21 men")

You retrieve notes from a variable by, for example,

  Cmd> getnotes(x)
  (1) "Heights of Stat 1001 students"
  (2) "collected Fall 1997"
  (3) "There were 29 women and 21 men"

@@@@use_with_inforead#Use with inforead()
One useful trick is to use inforead() to retrieve the comment lines
associated with a data set in a file readable by read() and matread()
(see topics 'matread_file' and inforead()) and then use attachnotes() to
attach them to the matrix:

  Cmd> y <- read("macanova.dat", "irisdata", quiet:T)

  Cmd> attachnotes(y, inforead("macanova.dat", "irisdata", quiet:T))

@@@@notes_keyword#Keyword 'notes'
You can also attach notes using keyword phrase 'notes:Notes' on
vector(), matrix(), array(), structure(), macro() or any of the plotting
commands, where Notes is a CHARACTER scalar or vector.  For example,

  Cmd> x <- array(x, notes:Notes) # Notes a CHARACTER vector

  Cmd> plot(x, y, notes:"Plot of height vs weight")

@@@@notes_in_files#Notes in files
Commands matprint(), matwrite() and macrowrite() automatically write any
attached notes in a form that is readable by read(), matread() and
macroread().  See topic 'matread_file'

@@@@propagation_of_notes#Propagation of notes
Generally notes do not "propagate" except in a few situations when the
result of a function is essentially the same as an argument to that
function.  Here are the specific situations when a copy of any notes
attached to x is attached to y.
    y <- x
    y <- vector(x [,labels:Labels]), when isvector(x) is True
    y <- matrix(x [,labels:Labels]), when ismatrix(x) is True
    y <- matrix(x, nrows(x) [,labels:Labels]), when ismatrix(x) is True
    y <- array(x, [,labels:Labels])
    y <- array(x,dim1,dim2,.. [labels:Labels]), when all the new
         dimensions match those of x
    y <- strconcat(x [,labels:Labels] [,compnames:Names]) when
         x is a structure.

@@@@see_also#Cross references
See also topics attachnotes(), getnotes(), appendnotes(), vector(),
matrix(), array(), structure(), macro(), list(), 'graph_keys'.
@@@@______

====nrows()#variables
%%%%
nrows(x), x a matrix or generalized matrix
%%%%
@@@@usage_and_examples#Usage and examples
nrows(x) returns the number of rows of matrix argument x.  If x has more
than two dimensions, no more than two dimensions may exceed 1 and it is
treated as described in topic 'matrices'.

Examples:
  Cmd> x <- array(run(24),1,6,1,4); y <- run(7)

  Cmd> vector(nrows(x),ncols(x))
  (1)           6           4

  Cmd> vector(nrows(y),ncols(y))
  (1)            7            1

  Cmd> vector(nrows(y'),ncols(y'))
  (1)           1           7

If x is a structure, nrows(x) is a structure.  If xi is the i-th
component of x, the i-th component of nrows(x) is nrows(xi).

@@@@see_also#Cross references
See also topics ncols(), dim(), ndims(), length(), 'structures'.
@@@@______

====NULL#null variables,variables
%%%%
x <- NULL creates a NULL variable
isnull(x) tests whether a variable is NULL.
%%%%
@@@@description#Description
A NULL variable is a special type of variable.  Unlike REAL, LOGICAL or
CHARACTER variables, a NULL variable contains no data.  You might think
of it as an completely empty variable.  Many functions and commands such
as anova(), regress() and print() that are primarily executed for their
"side effects" return a NULL variable as value.

@@@@working_with_NULL_variables#Working with NULL variables
You can explicitly create a NULL variable by
   Cmd> nullvar <- NULL
or
   Cmd> nullvar <- print("Hello!") # value of print() is NULL

You can use isnull() to test whether a variable is NULL.

  Cmd> isnull(NULL, PI, T, "hello", nullvar)
  (1) T       F       F       F       T

See isnull() for details.

@@@@limitations#Limitations
For obvious reasons, you can't do arithmetic or comparisons with NULL
variables and most commands and functions do not accept NULL variables
as arguments.

@@@@NULL_arguments#NULL arguments
A few functions such as vector(), hconcat(), vconcat(), sum(), prod(),
min() and max() do accept NULL arguments.  For example, vector(NULL,a,b)
and min(NULL,a,b) are equivalent to vector(a,b) and min(a,b),
respectively.  Here is an example where this might be useful.

  Cmd> x <- run(10); fstats <- NULL # or fstats <- vector(NULL)

  Cmd> for(i,run(1000)){regress("{.1*x+rnorm(10)}=x",silent:T)
       fstats <- vector(fstats,SS[2]/(SS[3]/DF[3]));;}

This creates a random sample of F-statistics based on a regression of y
on x where y = .1*x + rnorm(10) (see regress(), 'models', rnorm())
Although fstats starts out NULL, by the end of the first trip through
the loop, it contains the first F-statistic.  Without NULL variables,
the loop would have to be something like the following:

  Cmd> for(i,run(1000)){
     regress("{x+rnorm(10)}=x",silent:T); fstats <- \
      if(i==1){SS[2]/(SS[3]/DF[3])}else{vector(f,SS[2]/(SS[3]/DF[3]))}}

A better way to implement this example would probably be initialize by
fstats <- rep(0,1000), and save each value by fstats[i] <-
SS[2]/(SS[3]/DF[3]).

@@@@see_also#Cross references
See also topics 'for' and 'if'.
@@@@______

====number%#variables,syntax,missing values
%%%%
Type 'help(number)' for information on how to enter numbers and how
  numbers are printed.
%%%%
@@@@entering_numbers_and_missing_values#Entering numbers and missing values
You enter numbers as integers with or without out a decimal point, as
decimal numbers, or using exponential notation (X.XXeY or X.XXEY is XX.X
* 10^Y).

  Cmd> a <- 65535 # same as a <- 65535. or a <- 65535.0000

  Cmd> a <- -3141.592654; b <- .0000415; c <- 1000000

  Cmd> a <- -3.141592654e3; b <- 4.15E-5; c <- 1e6# same as preceding

For greater readability of long numbers, you can use '_' to separate
digits in the mantissa (the entire number without 'e' or 'E' or the part
before 'e' or 'E').

  Cmd> a <- -3_141.592_654e4 # same as a <- -3141.592654e4

Warning: _3_141, for example, is a legal variable name, not a number.

Fortran style double precision numbers like -3.14592654d3 and 4.15D-5
are read as if the 'd' or 'D' were 'e' (except by read() and matread()).

It is an error to attempt to enter a number that is too large to be
represented in the computer.  For example,

  Cmd> d <- 3.1e5000

is an error.  On most computers the largest numbers are about +-2^1024 =
+-1.79769e+308 and the smallest nonzero numbers are about +-2^(-1024) =
5.56268e-309.

You enter MISSING values using the symbol '?'.

  Cmd> e <- vector(1,2,3,?,4,5,?) # vector with 2 MISSING values.

Other representations for MISSING such as '*' and '.' which are
recognized by vecread() are not recognized in MacAnova commands.
However, since NA is a predefined locked REAL scalar with value MISSING,

  Cmd> e <- vector(1,2,3,NA,4,5,NA) # vector with 2 MISSING values

works fine (unless you have deleted NA).

@@@@numbers_and_missing_values_in_output#Numbers and missing values in output
By default, most numeric output is printed using a hybrid between
integer, decimal and exponential format.  MISSING values are normally
printed as 'MISSING'.

  Cmd> vector(100*PI, 1e6*PI, PI/100, PI/1e6)
  (1)       314.16   3.1416e+06     0.031416   3.1416e-06

  Cmd> vector(34, ?)
  (1)           34      MISSING

You can change these defaults by setoptions() keywords 'format' and
'missing'.  Here is an example:

  Cmd> setoptions(missing:"NA", format:"12.4f")

  Cmd> vector(100*PI, 1e6*PI, PI/100, PI/1e6)
  (1)     314.1593 3141592.6536       0.0314       0.0000

  Cmd> vector(34, ?)
  (1)      34.0000           NA

See topics setoptions(), 'options', print().

@@@@see_also#Cross references
See also topic 'syntax'.
@@@@______

====options#control,missing values,output,random numbers,general
%%%%
setoptions(option1:value [,option2:value ... ] [,badoptok:T]) option1,
  option2, ...  names of options, sets option values
getoptions(option1:T [,option2:T ... ] [,badoptok:T]), option1, option2,
  ...  option names of options, retrieves option values
List of options that may be set and retrieved
  Option name          Values (* = default)
  angles               "radians"*, "degrees" or "cycles"
  batchecho            T* or F
  dumbplot             T* or F
  errors               integer >= 0
  findmacros           "yes"*, "silent" or "no"
  font                 quoted string ("McAOVMonaco"*) [Mac]
  fontsize             integer > 0 (9) [Mac]
  format               quoted string ("12.5g"*)
  fstats               T or F*
  height               integer >= 0 (screen size*)
  history              integer >= 0 (100*)
  inline               T or F*
  keyboard             integer >= 0 (2*) [Windows]
  labelabove           T or F*
  labelstyle           "("*, "[", "{", "<", "/", "\\"
  lines                integer >= 0 (screen size*) [same as 'height']
  matchdelay           integer >= 0 [windowed versions only]
  maxlinelen           integer >= 80
  maxwhile             integer >= 10 (1000*)
  minpvalue            0 <= number <= .001 (1e-8)
  missing              quoted string <= 20 characters ("MISSING"*)
  nsig                 0 < integer <= 20 (5*)
  prompt               quoted string <= 20 characters ("Cmd> "*)
  pvals                T or F*
  quiet                T or F*
  restoredel           T* or F
  savehistry           T* or F [not limited memory DOS]
  scrollback           T or F* [windowed versions only]
  seeds                2 integers > 0 or both 0*
  tekset               CHARACTER vector of length 2 [non-windowed
                       Unix/Linux only]
  traceback            T or F*
  update               T or F [not windowed versions]
  vecread              "byfields" or "notbyfields"*
  warnings             T* or F
  wformat              quoted string ("16.9g"*)
  width                integer >= 30 (screen size*)
For details on an option, type help(options:Option) where Option is a
quoted option name.  Example: help(options:"nsig").
%%%%
@@@@introduction#Introduction
MacAnova has a variety of options you may set. These control or affect
output formatting, "dumb" graph size, the units used by trigonometric
functions, the string printed for MISSING values, the command line
prompt, macro creation, while loops, random number generation and the
action of save(), asciisave() and restore() (not an exhaustive list).

It may be helpful to think of options as hidden variables with LOGICAL,
CHARACTER or REAL values.  You use setoptions() to change their values
and getoptions() to retrieve their values.

You can get a brief list of options names with permissible values by
typing 'usage(options)'.

You can get an description of an individual option by typing
help(options:optionName), where optionName is the quoted name of the
option.  For example, help(options:"format") gives information on
option 'format'.

This topic lists all option that may be set.  Permissible values for
each option are in parentheses after the option name, usually with the
default value indicated.  A quoted string ("radians", for example) can
be replaced by a CHARACTER scalar and T or F can be replaced by a
LOGICAL scalar.
@@@@______

                      Options that may be set
@@@@angles#Option 'angles'
angles ("radians", "degrees" or "cycles", default = "radians")
                                 Example: setoptions(angles:"cycles")
  The value specifies the angular units assumed for sin(), cos(), tan(),
  asin(), acos(), atan(), cpolar(), hpolar(), crect(), hrect() and
  unwind().  The default value is "radians".  When 'angles' is
  "degrees", 360 is equivalent to 2*PI radians; when it is "cycles", 1
  is equivalent to 2*PI radians.  See also topic 'transformations'.

@@@@batchecho#Option 'batchecho'
batchecho (T or F, default = T)  Example: setoptions(batchecho:F)
  The value determines whether command lines that are read from a file
  by batch() are echoed to output.  True means echo; False means don't
  echo.  It is ignored when you use keyword 'echo' on batch().  See
  batch().

@@@@dumbplot#Option 'dumbplot'
dumbplot (T or F, default = F)   Example: setoptions(dumbplot:F)
  The value affects the default behavior of all plotting commands
  (plot(), chplot(), lineplot(), addpoints(), boxplot(), ...).  When it
  is True, these commands make "dumb" plots, that is plots using only
  characters such as could be produced on a printer with no graphics
  capability.  When 'dumbplot' is False, high resolution graphs are
  drawn.  It is ignored when you use keyword 'dumb' on a plotting
  command.  In non-interactive mode, 'dumbplot' is always True.

  When you use spool() to save your output to disk and 'dumbplot' is
  True, copies of all your plots will be spooled.

@@@@errors#Option 'errors'
errors (integer >= 0)            Example: setoptions(errors:20)
  The value n is the maximum number of errors tolerated.  n = 0 means
  errors will not be counted.

  When setoptions(errors:n) is executed from a batch file, n is used
  only until entry from the keyboard is next needed.  If more than n
  errors are found while a batch file is being read, reading from all
  current batch files is terminated.

  In interactive mode, 'errors' is initially set to 0 (ignore errors).
  If it is not reset, use of batch() temporarily sets the error limit to
  1; it reverts to 0 when commands from the batch file are completed.

@@@@findmacros#Option 'findmacros'
findmacros ("yes", "silent" or "no", default = "yes")
                                 Example: setoptions(findmacros:"no")
  The value controls the behavior of MacAnova when it encounters what
  looks like a call to a macro, but no macro with the name is defined.
  When 'findmacros' is "yes" or "silent", MacAnova searches all the
  files in pre-defined CHARACTER variable MACROFILES (see getmacros()
  and addmacrofile()) for the macro.  If a macro with that name is
  found, it is read in and then executed.  When 'findmacros' is "no", no
  search is made, resulting in an error.  When 'findmacros' is "yes", a
  warning message is printed before the search, and another one if the
  search is unsuccessful.  When 'findmacros' is "silent" or "no", no
  special messages are printed.

@@@@font#Option 'font'
font (quoted string)             Example: setoptions(font:"Courier")
  This option is only available on Mac OS 9.  The value is the name of
  the font used in the active command/output window and any additional
  windows that you may open from this window.  The value should be the 
  name of an available font such as "Courier" or "Monaco".  You can set
  both options 'font' and 'fontsize' by, for example, 
  setoptions(font:"Courier 12") (see 'fontsize' below).  The default 
  value of 'font' is "McAOVMonaco".

  setoptions(font:"default") restores the default font and size.  See
  options 'fontsize' below.

  When you change the font, you will almost certainly want to choose a
  non-proportional font such as "Courier" or "Monaco", that is, a font
  for which all characters, including spaces, have the same width.  If
  not, columns will not line up and, in general, output will be hard to
  read.

  If you regularly prefer a font other than the default font, you might
  want to set this option in your startup file.  See topic 'customize'.

@@@@fontsize#Option 'fontsize'
fontsize (integer > 0)           Example: setoptions(fontsize:18)
  The value is the size of the font used in the command/output window
  and any additional windows you may open from this window.  Option
  'fontsize' is available only in Mac OS 9 versions, for which the
  default value is 9.

@@@@format#Option 'format'
format (quoted string, default "12.5g")
                                 Example: setoptions(format:"13.6f")
  The value specifies the default format for printing.  For example, if
  the value of 'format' is "12.5g", most output will be in floating
  point form with 5 significant digits and a maximum width of 12
  characters.

  The value must be of the form "w.dg" (floating point with d
  significant digits and width w characters, including sign and
  exponent), or "w.df" (fixed point format with d digits after the
  decimal and minimum width w).  If w is omitted (for example, ".5g") it
  is taken to be d+7.  Examples are "10.5f" (fixed point with 5 decimal
  places and total width of 10) and ".15g" (floating point with 15
  significant digits and width 22).  See print() for more discussion of
  format specification.

  When setting 'format', you can put the format type specifier ('f' or
  'g') at the start of format.  For example, setoptions(format:"f10.6")
  is equivalent to setoptions(format:"10.6f").  When you retrieve the
  value using getoptions(format:T), 'f' or 'g' is always at the end.

  If you omit the width w (setoptions(format:".10g")), w = d+7 is
  assumed ("17.10g").  If you try to set the format so that w > 27 or d
  > 20, 27 and 20 are used, respectively.

  The 'g' format is a hybrid of integer format, decimal format with no
  exponent, and exponential format.  There is no purely exponential
  format available.  See topic 'number'.

@@@@fstats#Option 'fstats'
fstats (T or F, default F)       Example: setoptions(fstats:T)
  The value affects the default behavior of anova(), robust() and
  fastanova().  F-statistics are printed only when the value is True.
  The value of option 'fstats' is ignored when keyword 'fstats' is used
  on these commands.

  Option 'fstats' affects manova() only when 'byvar:T' is an argument.

@@@@height#Option 'height'
height (integer >= 0, default depends on screen size)
                                 Example: setoptions(height:20)
  The value is the assumed number of lines of output that will fit on
  the screen or in the command/output window.

  If nLines is the value of 'height', under Unix/Linux and DOS, whenever
  nLines-1 lines of output printed by a single command line, MacAnova
  will print "Hit RETURN to continue or q RETURN to go to next command
  line:" and then pause.  If command line editing is available, the
  message is "Press 'q' to quit, 'j' or 'n' to see next line, any other
  key to continue".

  The value of 'height' also affects the default size of stemleaf
  displays and "dumb" plots.

  When the value of 'height' is 0, counting of output lines is
  suppressed and the default size of stemleaf displays and "dumb" plots
  is 24.

  On Mac OS 9, the value of 'height' may be reset when the output
  window is resized; the only effect of the value is on the number of
  lines in a "dumb" plot.

  The value of 'height' can be predefined using the -l command line 
  option.  See topic 'launching'.

  The value of option 'height' is ignored when keyword 'height' is used
  on print(), write(), matprint(), matwrite() and error() or on plotting
  functions such as plot() and boxplot() (see 'graph_keys').

  See topics stemleaf(), 'graphs'.

@@@@history#Option 'history'
history (integer >= 0)           Example: setoptions(history:200)
  The value is the number of command lines that are saved and may be
  retrieved.  The default value for history is 100.  

  When the value of 'history' is 0, no command lines are saved.

@@@@inline#Option 'inline'
inline (T or F, default = F)     Example: setoptions(inline:T)
  The value specifies the default method of macro expansion, in-line
  when the value is True or out-of-line when it is False.  The value of
  option 'inline' is ignored when you use keyword 'inline' on macro() or
  when you use macroread() to read a macro with 'INLINE' or 'OUTLINE' on
  its header line.  See topics macro(), macroread(), 'macros',
  macro_files.

@@@@keyboard#Option 'keyboard'
keyboard  (integer >= 0)         Example: setoptions(keyboard:1)
  This currently has an effect only in the Windows version when using a
  non-US keyboard with an Alt Gr key.  The value determines whether
  codes generated by key combinations involving the Alt Gr key are
  recognized.  When keyboard = 2 (the default), any such key
  combinations are recognized.  When keyboard = 1, only key combinations
  associated with ASCII codes between 32 (space) and 126 (~) are
  recognized.  When keyboard = 0, no Alt Gr key combinations are
  recognized.

  Note: This value of 'keyboard' should not affect US keyboard
  configurations.  The option is provided to allow modification of
  recognition of Alt Gr combinations in case there are problems with the
  default behavior.  Other values may have special meaning in the
  future.

@@@@labelabove#Option 'labelabove'
labelabove (T or F, default = F)   Example: setoptions(labelabove:T)
  This option specifies the placement of default coordinate labels when
  printing variables without labels (see topic 'labels').

  When the value is True, the values for the last subscript (only
  subscript in the case of vectors) are printed above the data instead
  of all the subscripts being printed in the left margin.  This has no
  effect on the printed labels of CHARACTER varables which are always at
  the left.  The effect is the same as if the variable had labels which
  were all of the form rep("@",dimsize).  The default value is False.

@@@@labelstyle#Option 'labelstyle'
labelstyle ("(", "[", "{", "<", "/", "\\", default = "(")
                                 Example: setoptions(labelstyle:"[")
  This option specifies the style used in printing coordinate labels for
  unlabelled variables (see topic 'labels').  For example, when its
  value is "[", '[' and ']' are used instead of the default '(' and ')'.

@@@@lines#Option 'lines'
lines (integer >= 0, default depends on screen size)
                                 Example: setoptions(lines:20)
  Option 'lines' is the same as option 'height' (see above).  It is
  retained for compatibility with earlier versions.

@@@@matchdelay#Option 'matchdelay'
matchdelay (integer >= 0, default 20) (Macintosh OS 9 only)
                                 Example: setoptions(matchdelay:30)
  This sets the amount of time a matching left parenthesis or bracket is
  highlighted when you type a right parenthsis or bracket.  A value of 0
  turns off such highlighting.  The unit is ticks (1/60 second).

@@@@maxlinelen#Option 'maxlinelen'
maxlinelen (integer >= 80, default 2000)
                                 Example: setoptions(maxlinelen:5000)
  This provides an upper limit on the length of lines from a file that
  can be completely read by vecread(), read(), matread() and
  macroread().  It also applies when reading from a CHARACTER variable
  using keyword 'string'.  If a longer line is found, you are warned
  that not everything in the line was read.

@@@@maxwhile#Option 'maxwhile'
maxwhile (integer >= 10, default 1000)
                                 Example: setoptions(maxwhile:50000)
  The value is the default upper limit on the number of repetitions of a
  while(){...} loop.  When the limit is exceeded the loop is terminated
  with an error message.

@@@@minpvalue#Option 'minpvalue'
minpvalue (0 <= number <= .001, default .00000001)
                                 Example: setoptions(minpvalue:5e-6)
  The value is the default lower limits for P-values to be printed as
  computed by GLM commands such as regress(), anova() or logistic().
  Values below the limit are printed as "> 1e-8", for example.  When the
  value is 0, P-values are always printed as computed.

  If the value provided has more than 2 significant digits (2.54e-6, for
  example) it is rounded (to 2.5e-6, for example) and a warning message
  is printed.

  Changing option 'minpvalue' doesn't affect values computed by cumxxx()
  functions (cumF(17.975,5,45,upper:T), for example) or by macro
  twotailt().

@@@@missing#Option 'missing'
missing (quoted string with length <= 20 characters, default "MISSING")
                                 Example: setoptions(missing:"NA")
  The value is the default string used to print MISSING REAL or LOGICAL
  values.  For example, after setoptions(missing:"NA") any MISSING
  values will be printed as "NA" instead of the usual "MISSING".  The
  value of option 'missing' is ignored when you use keyword 'missing' on
  print() or write().  See print(), write().

  Changing option 'missing' does not affect the internal representation
  of MISSING or what gets written by matprint() and matwrite().

@@@@nsig#Option 'nsig'
nsig (0 < integer <= 20, default = 5)
                                 Example: setoptions(nsig:10)
  The value is the maximum number of significant digits or decimals to
  be used in most numerical output.  Its value is linked to that of
  option 'format'.  If the value of format is "w.dg" or "w.df", then the
  value of nsig is d.  setoptions(nsig:d) is equivalent to
  'setoptions(format:"w.dg")' where d is a positive integer and w = d+7.
  See option 'format' above.

@@@@prompt#Option 'prompt'
prompt (quoted string of no more than 20 characters, default = "Cmd> ")
                                 Example: setoptions(prompt:">> ")
  The value is printed at the start of each command line.  For example,
  after setoptions(prompt:"Next? "), each line will start with "Next? "
  instead of "Cmd> ".  In all versions except Mac OS 9, the initial
  value of 'prompt' can be set by command line flag -prompt (see
  'launching').

  When setoptions(prompt:Prompt) is executed in a batch file (see
  batch()), the new prompt remains in effect only until the commands in
  the file are finished.  Since a startup file (see 'customize') is
  executed as a batch file, this option cannot be usefully set in a
  startup file since the prompt is forgotten when the batch file is
  completed.

@@@@pvals#Option 'pvals'
pvals (T or F, default = F)      Example: setoptions(pvals:T)
  The value affects the default behavior of all the GLM commands except
  for robust() and screen().  It affects manova() only when keywords
  'byvar' or 'fstats' are used.  When the value is True, P values for
  t-, F- and chi-squared statistics are printed; when it is False, P
  values are not printed.  The value of option 'pvals' is ignored when
  you use keyword 'pvals' as an argument to a GLM command.

@@@@quiet#Option 'quiet'
quiet (T or F, default = F)       Example: setoptions(quiet:T)
  When True, all output is suppressed except for error messages and the
  input prompt (Cmd> ).  Option 'quiet' differs from other options in
  that its value is associated with a the macro currently running.

  A macro inherits the value of quiet from the prompt level, if called
  there, or from the value in a macro that calls it.

  When 'quiet' is set by setoptions() in a macro, it reverts to the
  former value when leaving the macro.

@@@@restoredel#Option 'restoredel'
restoredel (T or F, default = T)  Example: setoptions(restoredel:F)
  The value determines whether existing variables will be deleted by
  restore().  When the value is True, they will be deleted; when it is
  False they will be deleted only when they are overwritten.  The value
  of 'restoredel' is ignored when you use keyword 'delete' on restore().

@@@@savehistry#Option 'savehistry'
savehistry (T or F)   (note spelling)
                                 Example: setoptions(savehistry:F)
  The value determines whether a history of recent command lines will be
  saved by save() and asciisave().  When the value is True such a
  history is saved and will be automatically restored by restore(); when
  the value is False, the history is not saved.  Option 'savehistry' is
  ignored when keyword 'history' is used on save() and asciisave().  The
  default value of 'savehistry' is True except in non-interactive mode.

  'savehistry' is not available on versions such as the limited memory
  DOS version that do not maintain such a history.

@@@@scrollback#Option 'scrollback'
scrollback (T or F, default = F) Example: setoptions(scrollback:T)
  The value determines when the command/output window will be
  automatically scrolled back to the beginning of output that is longer
  than the window can hold.  When the value is True, the window is
  scrolled back so that the most recent command line is visible.  When
  the value is False, no such scrolling takes place.  On help(), this
  default behavior can be overridden by the help() keyword 'scrollback'.
  Option 'scrollback' is available only in windowed versions.

@@@@seeds#Option 'seeds'
seeds (vector of 2 integers > 0 or both 0, default = vector(0,0))
                  Example: setoptions(seeds:vector(6542821,6228765))
  The value is a REAL vector of length 2, say vector(n1,n2), where n1 >=
  0 and n2 >= 0 are integers <= 2147483399.  These values are used and
  updated by random number generators runi(), rnorm(), rbin() and
  rpoi().

  You normally set this option by setseeds() since setseeds(n1,n2) is
  equivalent to setoptions(seeds:vector(n1,n2)).

  When the value is vector(0,0), the first use of runi(), rnorm(),
  rpoi() or rbin() causes the seeds to be set to pseudo-random values
  determined from the time of day.

@@@@tekset#Option 'tekset'
tekset (CHARACTER vector of length 2)
       Example: setoptions(tekset:vector("\033[?38h\0338","\033\003"))
  The value is a CHARACTER vector of length 2, say vector(ToTek,
  FromTek).  ToTek is the CHARACTER string that switches the terminal
  emulator you are using to Tektronix 4014 mode and FromTek is the
  CHARACTER string that switches out of Tektronix 4014 mode.  These are
  used before starting and after finishing a plot, and are used by
  Mouse().

  When ToTek is "", no code is sent to switch to Tektronix mode.
  Similarly, when FromTek is "", no code is sent to switch back.

  When MacAnova is running under Xterm on a Unix/Linux workstation, the
  default is as in the example above, which could also be set by
   Cmd> setoptions(tekset:vector(putascii(27,91,63,51,56,104,27,56,\
      keep:T), putascii(27,3,keep:T)))

  When MacAnova is not running under Xterm, the default is
  vector("\035\0338", "\0332") which is equivalent to
  vector(putascii(29, 27, 56, keep:T), putascii(27, 50, keep:T))

  Both defaults initialize the character size to large.

  The non-Xterm default works for Macintosh program Versaterm.  For
  other terminal emulators, this option should be initialized in a
  startup file.  See topic 'customize'.  For example, for public domain
  program Kermit 3.0 for Windows/DOS computers, your startup file might
  contain the command (not tested)
    setoptions(tekset:vector("\33[?38h\0338","\033[?38h"))

  For NCSA Telnet 2.6 for a Macintosh, use
    setoptions(tekset:vector("\033\014","\030"))

  Option 'tekset' is available only on Unix/Linux versions using
  Tetronix 4014 emulation for high resolution graphs.

@@@@traceback#Option 'traceback'
traceback (T or F)               Example: setoptions(traceback:F)
  The value controls whether the chain of calling macros will be printed
  when an error occurs in a macro called by another macro.  It has no
  effect when an error does not occur in a macro.  When an error occurs
  in a macro and the value is F (the default), only the name macro is
  printed.  When the value is true the name of the macro and, when that
  macro was called in a macro, the chain of calling macros is printed.

  This option makes use of the fact that expanded macros are prefaced by
  the header '{#)#macroname'. Because some error messages append about
  50 characters of input preceding the error, you may see some calling
  macro names in short macros.  Here is an example of what this means:

  Cmd> a <- macro("q + PI"); b <- macro("a()"); c <- macro("b()")

  Cmd> setoptions(traceback:F); c() # no traceback (q not defined)
  ERROR: arithmetic with undefined operand
  UNDEF + REAL in macro a near setoptions(traceback:F); {#)#c
  {#)#b
  {#)#a
  q + PI

  Cmd> setoptions(traceback:T); c() # traceback
  ERROR: arithmetic with undefined operand
  UNDEF + REAL near setoptions(traceback:T); {#)#c
  {#)#b
  {#)#a
  q + PI
   in macro a
   called by macro b
   called by macro c

  There may be a few error messages unaffected by the value of
  'traceback'.

  See topic macro_syntax for information about writing macros.

@@@@update#Option 'update'
update (T or F)                  Example: setoptions(update:F)
  The value controls whether the screen will be updated (previous
  commands and output re-printed) after a high resolution plot (True
  means update; False means don't update).  The default value of update
  is True in DOS versions and False in non-windowed Unix/Linux versions.

  Option 'update' is not available in a Windowed version.

@@@@vecread#Option 'vecread'
vecread ("byfields" or "notbyfields", default = "notbyfields")
                                 Example: setoptions(vecread:"byfields")
  The value specifies the default mode for vecread() when reading REAL
  data.  When it is "notbyfields", the default value for vecread()
  keyword 'byfields' is False; when it is "byfields" the default value
  of 'byfields' is True.

  Option 'vecread' is ignored by vecread() when it is reading CHARACTER
  data.

@@@@warnings#Option 'warnings'
warnings (T or F, default = T)   Example: setoptions(warnings:F)
  The value controls whether MacAnova will suppress the printing of
  warning messages (those that start with "WARNING:").  Such lines will
  be printed only when the value of 'warnings' is True.  Setting
  'warnings' to False can be useful when doing arithmetic with and
  transformations of vectors or matrices with missing data.  However,
  since many warning messages are quite important, it should be used
  with caution.  When you change 'warnings' to False, you should use
  setoptions(warnings:T) to restore the usual behavior as soon as
  possible.

@@@@wformat#Option 'wformat'
wformat (quoted string, default = "16.9g")
                                 Example: setoptions(wformat:".17g")
  The value specifies the default format for the commands write() and
  matwrite().  For example, if the value is "16.9g", most output will be
  in floating point form with 9 significant digits and a maximum width
  of 16 characters.

  See option 'format' above for more information about permissible
  values.

@@@@width#Option 'width'
width (integer >= 30, default depends on screen width)
                                 Example: setoptions(width:65)
  The value is the number of characters assumed to fit on a line on the
  screen or in the window.  This number, together with the current
  formatting options, determines how many items are printed per line and
  the width of "dumb" plots.

  The value of option 'width' is ignored when keyword 'width' is used on
  print(), write(), matprint(), matwrite() and error() and on plotting
  functions such as plot() and boxplot() (see 'graph_keys').

  On Unix/Linux and DOS 'width' may be initialized by the -w command
  line flag (see topic 'launching').  On Mac OS 9, 'width' may be
  reset when the output window is resized.

  Some output does not respect this limit.
@@@@______

====outer()#matrix algebra
%%%%
outer(x1, x2, ...), x1, x2, ... REAL
%%%%
@@@@usage#Usage
outer(x1, x2) returns a matrix or array which is the "outer product" of
REAL variables x1 and x2.  The dimensions of the result are the
joined dimensions of the arguments.

After result <- outer(x1,x2), the elements of the result are
  result[i,j,k,...,l,m,n,...] = x1[i,j,k,...] * x2[l,m,n,...].

outer(x1, x2) is equivalent to array(vector(x1)*vector(x2)',
vector(dim(x1), dim(x2))).

outer(x1, x2, x3) is mathematically equivalent to outer(outer(x1,x2),
x3) and in general outer(x1, x2, x3, ..., xk) is mathematically
equivalent to outer(outer(...(outer(x1,x2), x3), ...), xk).  The
elements of the result are all possible k-way products of elements from
each of the arguments.

@@@@multi_dimensional_contrasts#Multi dimensional contrasts
One use for outer() is to construct multidimensional contrasts that are
products of 1 dimensional contrasts.  Suppose c1, c2 and c3 are vectors
of main effect contrast coefficients for each factor for a 3 factor
design.  Then after anova("y=a*b*c"),

  Cmd> contrast("a.b.c", outer(c1,c2,c3))

computes results for the three way product contrast that is part of the
a.b.c interaction.

@@@@see_also#Cross references
See also topics contrast(), array(), 'matrices'
@@@@______

====padto()#time series
%%%%
padto(x,n), x a REAL vector or matrix, n > 0 an integer
%%%%
@@@@usage_and_example#Usage and example
padto(x,n) creates a new matrix or vector from REAL vector or matrix x
by adding n - nrows(x) rows of all zeros so as to bring the total number
of rows to n.  When n < nrows(x), the last nrows(x) - n rows of x are
deleted to bring the number down to n.  n must be a positive integer.

The principal use of padto() is to add zeros to a time series after
subtracting the mean or other estimate of trend but before computing its
Fourier transform, as in rft(padto(x-sum(x)/nrows(x),S)), where S is the
number of frequencies desired.  If x has several columns, they all get
padded simultaneously.

Example:
  Cmd> padto(vector(1,2,2)',4) # pad row vector to matrix with 4 rows
  (1,1)           1           2           2
  (2,1)           0           0           0
  (3,1)           0           0           0
  (4,1)           0           0           0
@@@@______

====partacf()#time series
%%%%
partacf(rho), rho a REAL matrix whose columns are autocorrelations
partacf(phikk, inverse:T), phikk a REAL matrix whose columns are
  partical autocorrelations
%%%%
@@@@usage#Usage
partacf(rho), where rho is a REAL vector, computes the partial
autocorrelations corresponding to the autocorrelation function in the
REAL vector rho.  Row k of rho should contain the lag k autocorrelation.
The Levinson-Durbin algorithm is used.

If rho is a matrix, partacf(rho) is a matrix of the same shape whose
j-th column contains partial autocorrelations corresponding to
autocorrelations in column j of rho.

If any column of rho is not a valid autocorrelation function, that is,
it does not define a positive definite Toeplitz matrix, a warning
message is printed.

partacf(phikk,inverse:T) is the inverse function to partacf.  Each
column of REAL vector or matrix phikk is considered to be the partial
autocorrelation function of a time series.  The corresponding column of
the result is the corresponding autocorrelation function.  All the
elements of phikk must be less than 1 in absolute value.

@@@@see_also#Cross references
See also yulewalker().
@@@@______

====paste()#output,missing values
%%%%
paste(arg1, arg2, ... [,format:Fmt,sep:C,intwidth:Iw,charwidth:Cw,\
  missing:S]), Fmt, C, and S CHARACTER scalars, Iw and Cw integers > 0
paste(arg,multiline:T [,format:Fmt,sep:Cs,linesep:Cl,missing:S]), where
  Cs and Cl are CHARACTER scalars consisting of a single character.
'iw', 'cw', 'fmt', and 'just' are synonyms for 'intwidth', 'charwidth',
  'format' and 'justify'
%%%%
@@@@usage#Usage
paste(arg1, arg2, ...) returns a CHARACTER scalar concatenating the
arguments.  For example, the value of
    paste("The answer is", run(7), "; ok?")
is the string "The answer is 1 2 3 4 5 6 7 ; ok?" .

An important use of paste() is in constructing labels for graphs (for
example, title:paste("Variable",j,"vs variable",i)).  It is also useful
for producing informative messages to be printed in a macro and can be
used to prepare nicely formatted lines for output.

The default behavior is to print the arguments separated by single
spaces, with exact integers printed as such, non-integers printed using
the default print format (see print(), subtopi 'options:"format"') with
leading spaces trimmed off, and missing values printed as "MISSING".  If
you have used setoptions() to replace "MISSING" by a different default
string, the replacement will be used.

A NULL non-keyword argument is ignored unless it is the only argument,
in which case paste(NULL) returns "".

@@@@sep_keyword#Keyword 'sep'
paste(arg1, arg2, ..., sep:S), where S is a CHARACTER variable or quoted
string, uses S to separate arguments rather than a space.  For example,
paste(run(5),sep:",") produces the string "1,2,3,4,5" and
paste("A","B","C","D","E",sep:"") produces the string "ABCDE".  No
separator is ever put before the first item in the output variable.  You
can have several instances of 'sep:S' with different separators, each
affecting later arguments until changed.

@@@@intwidth_keyword#Keyword 'intwidth'
paste(arg1, arg2, ..., intwidth:w), where w is a positive integer prints
each exact integer using at least w positions, padding on the left with
spaces if necessary.  For example, paste(12,intwidth:5) produces " 12".
You can use iw:w instead of intwidth:w.

@@@@format_keyword#Keyword 'format'
paste(arg1, arg2, ..., format:Fmt), where Fmt is a CHARACTER variable or
quoted string representing either a f-format ("10.5f" or "f10.5") or
g-format ("11.7g" or "g11.7") (see print()) prints any non-integer REALs
using format Fmt If the width is omitted (".7f") leading spaces will be
stripped off.  If the width is not omitted ("10.7f"), any non-integer
REAL variables printed will be formatted so as to use at least this
width.  If 'intwidth:w' has not previously appeared, this width will
also be used for integers.  You can use fmt:Fmt instead of format:Fmt.

@@@@charwidth_keyword#Keyword 'charwidth'
paste(arg1, arg2, ..., charwidth:w), w is a positive integer, uses at
least w character positions for any CHARACTER argument, padding on the
right with spaces if necessary, unless justify:"r" or justify:"c" is an
argument.  You can use cw:w instead of charwidth:w.

@@@@justify_keyword#Keyword 'justify'
paste(arg1, arg2, ..., justify:C), where C is "right", "left", or
"center" (or simply "r", "l", or "c"), specifies that any strings are to
be right justified, left justified or centered, respectively.  This has
no effect unless charwidth:w is specified and a string is shorter than
w.  The default is justify:"left".  You can use just:C instead of
justify:C.

@@@@missing_keyword#Keyword 'missing'
paste(arg1, arg2, ..., missing:String), where String is a quoted string
or CHARACTER scalar such as "?", uses String to represent a missing
value instead of "MISSING".  If a format has been specified with width >
0 longer than the length of String, String will be padded on the left to
make it have this width.

@@@@keywords_used_more_than_once#Keywords used more than once
You can use any of the keywords more than once anywhere in the argument
list, with each usage affecting the formatting of subsequent items until
changed by a new keyword phrase.  Putting it after all non-keyword
arguments, as illustrated above, is equivalent to putting it before
them.  For example, paste(sep:",",charwidth:5,a,b,c) is equivalent to
paste(a,b,c,sep:",", charwidth:5).

@@@@multiline_keyword#Keyword 'multiline'
paste(arg,multiline:T) has somewhat different behavior.  The result is
much as before, except, if arg is other than a row vector, the result is
a CHARACTER vector, with one element for each value of the first
dimension that is greater than 1.  Thus, if arg is a matrix or vector,
each element of the output is a character representation of a row of
arg. When you use 'multiline:T', there must be exactly 1 non-keyword
argument.  If arg is LOGICAL, it is first translated to REAL with True
and False becoming 1 and 0, respectively.  If arg is NULL, the result is
"".

paste(arg,multiline:T,linesep:Char), where Char is a string with just
one character such as ";" or "\n" (the end-of-line character), combines
the rows into a single CHARACTER scalar with each row separated by Char.
If arg is a row vector (just 1 row), Char is ignored.

Along with 'multiline:T', you can use keywords 'sep', 'format', and
'missing', but not 'intwidth' and 'charwidth'.  If it appears, the value
for 'sep' must be a string with just one character, for example, " "
(the default) or "\t".  Any leading or trailing blanks in each numerical
field are trimmed off when 'sep' is used.

paste() does not recognize keyword 'nsig'.

@@@@examples_without_multiline#Examples without 'multiline:T'
  Cmd> paste(sep:"-","tick","tock",sep:", ","ding",sep:"-","dong")
  (1) "tick-tock, ding-dong"

The first 'sep:"-"' could also come at the end.

  Cmd> paste("PI is",PI,format:".10f") # or "Pi is",PI,fmt:".10f"
  (1) "PI is 3.1415926536"

  Cmd> paste(format:"10.2f",sqrt(2),format:".15g",sqrt(2))
  (1) "      1.41 1.4142135623731"

  Cmd> paste("Blocks",DF[2],SS[2],SS[2]/DF[2],format:"7.3f",\
        (SS[2]/DF[2])/mse,charwidth:8,format:"13.6g",intwidth:2)
  (1) "Blocks    4       48.0368       12.0092  18.782"

In the preceding, 'cw', 'iw', and 'fmt' could replace 'charwidth',
'intwidth' and 'format'.

@@@@examples_with_multiline#Examples with 'multiline:T'
  Cmd> paste(x, multiline:T) # 3 by 5 matrix x
  (1) "10.322 9.5278 10.636 10.411 9.6343"
  (2) "9.9979 10.606 8.1604 MISSING 8.5926"
  (3) "8.6147 11.212 9.4683 7.7964 10.489"

  Cmd> paste(x,multiline:T,linesep:"\n",sep:",",\
        missing:"-99",format:"0.4f")
  (1) "10.3222,9.5278,10.6357,10.4106,9.6343
  9.9979,10.6057,8.1604,-99,8.5926
  8.6147,11.2120,9.4683,7.7964,10.4889"

@@@@see_also#Cross references
See also print().
@@@@______

====plot()#plotting
%%%%
plot(x,y [,add:T,impulses:T, lines:T] [other graphics keyword phrases]),
  where x is a REAL vector or scalar, y is a REAL vector or matrix
plot([Graph,] [x,y], keys:str), str a structure whose component names
  are graphics keywords
%%%%
@@@@usage#Usage
plot(x,y) makes a scatter plot of the data in vector x and vector or
matrix y using characters such as asterisks or diamonds as plotting
symbols.  If y has several columns, they are plotted with symbols
asterisk, diamond, cross, square, X, triangle, asterisk, dot, small
cross, diamond,..., thereafter cycling through the plotting symbols.

It is not an error when x or y is NULL; a warning message is printed and
no plotting occurs.

plot(x,y, symbols:c), where c is a CHARACTER or integer scalar, vector,
or matrix with ncols(c) == ncols(y), uses the elements of c as plotting
symbols as for chplot().  In particular, if c is a CHARACTER scalar
other than "###", it is used as a plotting symbol for all points (at
most first three characters).

plot(x,y,symbols:"###") labels each point with the row number when y is
a vector and with the column number when ncols(y) > 1.

plot(x,y,impulses:T [,symbols:c]) makes an "impulse" plot of y vs x,
drawing vertical lines from the x = 0 line to each point.  If y has
several columns, a different line type is used for each column.
However, since the lines will probably be superimposed, it may be hard
to interpret the resulting plot.

plot(x,y, lines:T [,impulses:T, symbols:c) does the same except the
points or impulses will be connected by lines similarly to lineplot().
You can also use keywords 'linetype' and 'thickness'.  See topic
'graph_keys'.

@@@@structure_first_argument#Structure first argument
plot(Str [,impulses:T]), where Str is a structure with at least two REAL
components, is equivalent to plot(Str[1], Str[2] [,impulses:T]).  For
example, plot(x,y) and plot(structure(x,y)) are equivalent.  Any
components of Str beyond the first two are ignored.

@@@@LASTPLOT_and_GRAPHWINDOWS#LASTPLOT and GRAPHWINDOWS
plot() normally creates or replaces GRAPH variable LASTPLOT which
encapsulates everything in the graph.  In addition, if the graph was
drawn in graphics window I, GRAPHWINDOWS[I] is made identical to
LASTPLOT (I is always 1 in non-windowed DOS and Unix/Linux versions).
Saving the plot information in LASTPLOT and GRAPHWINDOWS[I] can be
suppressed by including 'keep:F' as an argument.  See topics 'graphs'
and 'graph_assign' for information on GRAPH variables and special
variable GRAPHWINDOWS.

@@@@graph_variable_first_argument#Graph variable first argument
plot(graph,x,y [,impulses:T]) or plot(graph,Str [,impulses:T]), where
graph is a GRAPH variable, draws the plot encapsulated in graph, adding
to it the new information.  See topic 'graphs' for details on adding
information to a plot.

@@@@add_keyword#Keyword 'add'
plot(x,y [,impulses:T],add:T,...) is the same as plot(LASTPLOT,x,y
[,impulses:T],...)  drawing the graph encapsulated in LASTPLOT, adding
to it new information.  An equivalent way to do this is addpoints(x,y
[,impulses:T],...).

@@@@low_resolution_plot#Low resolution plot
If option 'dumbplot' has been set False (see subtopi
'options:"dumbplot"'), the plot will be a low resolution plot unless
'dumb:F' is an argument.

@@@@short_vector_for_x#Short vector for x
See topic 'graphs' for information on how a scalar or length 2 vector x
specifies equally spaced x-values, on how to save and print plots, and
on writing graphic information to a file.

@@@@graphics_keywords#Graphics keywords
Keywords 'dumb', 'lines', 'linetype', 'thickness', 'impulse', 'xmin',
'xmax', 'ymin', 'ymax', 'logx', 'logy', 'xlab', 'ylab', 'title',
'xaxis', 'yaxis', 'borders', 'ticks', 'xticks', 'yticks', 'xticklen',
'yticklen', 'xticklabs', 'yticklabs', 'height', 'width', 'pause',
'silent' and 'notes' may be used as for other plotting commands.  See
topics 'graph_keys', 'graph_border' and 'graph_keys'

plot([Graph,] keys:structure(x:x,y:y [other keyword phrases)) is
equivalent to plot([Graph,] x:x,y:y [other keyword phrases]).  See topic
'graph_keys' for details.

See topic 'graph_assign' for information on how to plot in graphics
window I by GRAPHWINDOWS[I] <- var, where var is a structure or GRAPH
variables.

@@@@examples#Examples
Examples:
  Cmd> plot(yhat1:yhat[,1],resid1:RESIDUALS[,1],\
        title:"Residuals vs yhat")

  Cmd> plot(X:1,run(20)^(.2*run(5)'),ylab:"Powers of X",\
        title:"X^.2, X^.4, X^.6, X^.8, and X", file:"ps.out",new:T)

  Cmd> plot(X:1,run(20)^(.2*run(5)'),ylab:"Powers of X",\
        title:"X^.2, X^.4, X^.6, X^.8, and X", logy:T)

@@@@see_also#Cross references
See also topics chplot(), lineplot(), addpoints(), addlines(),
addchars(), showplot(), colplot(), rowplot(), tek(), tekx(), vt(),
vtx().
@@@@______

====poisson()#glm,regression,categorical data
%%%%
poisson([Model] [, print:F or silent:T, incr:T, offsets:vec, pvals:T,\
  maxiter:m, epsilon:eps, coefs:F]), vec a REAL vector, m an integer >
  0, eps REAL > 0
%%%%
@@@@usage#Usage
poisson(Model) computes a log linear regression fit of the model
specified in the CHARACTER variable Model.  If y is the response
variable in the model it must be a REAL vector with y[i] >= 0.
Estimation is by maximum likelihood on the assumption that y[i] is
Poisson.  If any y[i] is not an integer a warning message is printed.

See topic 'models' for information on specifying Model.

poisson(Model,...) is equivalent to glmfit(Model,dist:"poisson",
link:"log",...).

@@@@side_effect_variables_created#Side effect variables created
poisson() sets the side effect variables RESIDUALS, WTDRESIDUALS, SS,
DF, HII, DEPVNAME, TERMNAMES, and STRMODEL.  The elements of
WTDRESIDUALS are the final weighted residuals in the iteratively
reweighted least squares fit to log(response).  See topic 'glm'.
Without keyword phrase 'inc:T' (see below), TERMNAMES has value
vector("","", ...,"Overall model","ERROR1"), DF has value vector(0,0,
...,ModelDF,ErrorDF) and SS has value vector(0,0,...,ModelDeviance,
ErrorDeviance).

@@@@analysis_of_deviance#Analysis of deviance
If, say, Model is "y=x1+x2", an iterative algorithm fits log(y) as a
linear function of x1 and x2.  A two line Analysis of Deviance table is
printed, with line 1 the diffence between the deviance from a model with
all coefficients 0 and the deviance of the estimated model, and line
2, labeled "ERROR", the deviance of the estimated model.  Under
appropriate assumptions, the latter can be used to test the goodness of
fit of the model.

@@@@incremental_fitting#Incremental fitting
poisson(Model,inc:T) computes the full Poisson model and all partial
models -- only a constant term, the constant and the first term, and so
on.  It prints an Analysis of Deviance table, with one line for each
term, plus the deviance of the complete model labeled as "ERROR" .
Each term's deviance is the reduction in deviance associated with that
term.

@@@@omitting_model#Omitting model
If you omit Model (poisson()), the model from the most recent GLM
command such as poisson() or anova(), or the model in CHARACTER variable
STRMODEL is assumed.

@@@@algorithm#Algorithm
Computations are carried out using iteratively reweighted least squares
with starting values derived from an unweighted least squares fit of
log(y + .25).

@@@@keywords
                     Other keyword phrases
Keyword phrase  Default  Meaning
  maxiter:m       50     Positive integer m is the maximum number of
                         iterations that will be allowed in fitting

  epsilon:eps    1e-6    Small positive REAL specifying relative error
                         in objective function (2*log likelihood)
                         required to end iteration

  offsets:OffVec  none   Causes model to be fit to log(p) to be 1*Offvec
                         + Model, where OffVec is a REAL vector the same
                         length as response y.  Note OffVec is in log
                         units.

See topic 'glm_keys' for information on keyword phrases print:F,
silent:T, coefs:F and pvals:T.

The default value for pvals can be changed by setoptions(pvals:T).  See
topic setoptions(), subtopic 'options:"pvals"'.

@@@@examples_on_use_of_offsets
                    Examples of the use of 'offsets'
  Cmd> poisson("y=x", offsets:3*x, inc:T, pvals:T)
The P value associated with x can be used to test the hypothesis H0:
beta1 = 3 in the model log(E[y]) = beta0 + beta1*x.

  Cmd> poisson("y=1", offsets:rep(log(10), length(y), inc:T, pvals:T)
The P value associated with the CONSTANT term can be used to test H0:
E[y] = 10, assuming y contains a random sample from a Poisson
distribution.
@@@@______

====polygamma()#transformations
%%%%
polygamma(x [,n]), x REAL with positive elements or a structure with
  REAL components with positive elements, integer n >= 0
%%%%
@@@@usage#Usage
polygamma(x,0) and polygamma(x) both return the digamma function (first
derivative of log(gamma(x))) of the elements of x, when x is a REAL
scalar, vector, matrix or array with positive elements.  The result has
the same shape as x.  You can use digamma(x) instead.

polygamma(x, n), where n > 0 is an integer returns the n-th derivative
of the digamma function ((n+1)-th derivative of log(gamma(x))).

polygamma(x, n, scale:T) returns (-1)^(n+1)*n!*polygamma(x,n).

For n >= 1, polygamma(x, n, scale:T) = sum((x+k)^(-n-1),k=0,1,2,...,oo).
In particular, polygamma(1,n,scale:T) computes zeta(n+1), where zeta(s)
is the Riemann Zeta function.

@@@@structure_argument#Structure argument
When x is a structure, all of whose non-structure components are REAL
with positive elements, polygamma(x [,n] [,scale:T]) returns a structure
of the same shape and with the same component names as x with each
non-structure component transformed by polygamma().

@@@@character_argument#CHARACTER argument
polygamma(x, n) can also be used when x is a CHARACTER variable and n,
if present, is a quoted string or CHARACTER scalar or REAL scalar.  The
result is a CHARACTER variable of the same shape as x describing the
transformation.  See example below.

Any element of x that is "" or starts with '@', '(', '[', '{', '<', '/'
or '\' is not modified.  This can be useful for creating labels for a
transformed variable.

@@@@examples#Examples
Examples:
  Cmd> polygamma(run(10)) # or polygamma(run(10),0), or digamma(run(10))
  (1)    -0.57722     0.42278     0.92278      1.2561      1.5061
  (6)      1.7061      1.8728      2.0156      2.1406      2.2518

  Cmd> polygamma(run(1,2,.25),1) # trigamma
  (1)      1.6449      1.1973      0.9348      0.7641     0.64493

  Cmd> polygamma(vector("x","y"),3) # or polygamma(vector("x","y"),"3")
  (1) "polygamma(x,3)"
  (2) "polygamma(y,3)"

  Cmd> print(nsig:17,polygamma(1,23,scale:T),name:"zeta(24)")
  zeta(24):
  (1)       1.0000000596081891

@@@@see_also#Cross references
See also digamma(), lgamma(), 'transformations'.

====polyroot()#time series,complex arithmetic
%%%%
polyroot(coefs), coefs a REAL matrix
%%%%
@@@@usage#Usage
polyroot(Coef) computes the real and possibly complex roots of the
polynomials specified by the columns of REAL matrix Coef.  If c[i] is
Coef[i,j], then the polynomial whose roots are found is
  x^n - c[1]*x^(n-1) - c[2]*x^(n-2) - ... - c[n-1]*x - c[n],
where n = nrows(Coef).  Note that the leading coefficient (of x^n) is 1,
and the coeficients are associated with descending powers of x.

NOTE: The sign assumed for Coef is not affected by variables ARSIGN or
MASIGN which are recognized by several macros in file Arima.mac.  Type
arimahelp(MASIGN) for details.

If Coef is n by m, the result returned is a n by 2*m matrix with the
real and imaginary parts of the roots associated with column j of Coef
in columns 2*j-1 and 2*j, that is in the standard fully complex form.
See topic 'complex'.

To find the roots of polynomial d[1]*x^n+d[2]*x^(n-1)+...+d[n]*x+
d[n+1], use polyroot(-d[-1]/d[1]) (when d is a matrix use
polyroot(-d[-1,]/d[1,])).

To find the roots of polynomial d[1]+d[2]*x+d[3]*x^2...+d[n+1]*x^n, use
polyroot(-reverse(d[-(n+1)])/d[n+1]) (when d is a matrix use
polyroot(-reverse(d[-(n+1),])/d[n+1,])).  See reverse().

@@@@use_with_autoreg_and_movavg#Use with autoreg() and movavg()
The form of the argument to polyroot is adapted to its use in evaluating
autoregressive and moving average operators.  If phi is a REAL vector
and x is a vector of white noise, autoreg(phi,x) generates a stationary
autoregressive series if and only if the roots computed by polyroot(phi)
are inside the unit circle, that is, max(creal(cpolar(polyroot(phi)))) <
1.  Similarly, movavg(theta,x) generates an invertible moving average
model if and only if all the roots computed by polyroot(theta) lie
inside the unit circle.

@@@@see_also#Cross references
See also topics autoreg(), movavg(), 'complex' and subtopic
'matrices:"complex_matrices".
@@@@______

====popmodel()#anova,glm,multivariate analysis,regression,residuals
%%%%
popmodel([all:T])
popmodel(canpop:T)
%%%%
@@@@introduction#Introduction
All GLM commands except screen(), for example regress() and anova(),
retain information (GLM information) internally for use by certain
functions such as coefs() and modelinfo() that provide results from the
most recent GLM command.  When a GLM command is run, information from
the previous GLM command, if any, is replaced.  When the GLM command is
in a macro, this may confuse the user who may expect that coefs(), say,
gives the same answer after the macro is used as before.

Commands pushmodel() and popmodel() allow a macro to save and restore
the current GLM information.

pushmodel() saves the current GLM information so that it can
subsequently be restored by popmodel().  Until a new GLM command has
been run or GLM information has been restored by popmodel(), there is no
GLM information available to commands such as secoefs() and modelinfo().

After the next prompt following the use of pushmodel(), the active model
before the first use of pushmodel() is restored (equivalent to an
automatic execution of popmodel(all:T)).

pushmodel() and popmodel() are intended to be used in macros.  A macro
can run pushmodel() before a GLM command and then run popmodel() before
finishing to ensure that the current GLM information is not changed.  Of
course, if the purpose of the macro is to change the information, it
should not use pushmodel() and popmodel().

The default maximum number of sets of GLM information that can be saved
is 2 (0 in limited memory DOS version).  On versions allowing command
line arguments you can change the default by '-savemodels N' where N >=
0 is an integer.  See 'launching'.

@@@@usage#Usage
popmodel() replaces the current GLM information by the GLM information
saved most recently by pushmodel().  It also deletes all GLM side effect
variables such as RESIDUALS and STRMODEL and then replaces them by side
effect variables appropriate to the model being restored.

popmodel(all:T) discards the current GLM information and all but the
first GLM information saved by previous use of pushmodel().

With either usage, when there is no information that has been saved by
pushmodel(), a warning message is printed and the current GLM
information is not discarded nor are side effect variables modified.

popmodel(canpop:T) returns True if there is saved GLM information that
could be restored by popmodel().  It does not change the current model
or side effect variables.

@@@@example#Example
Type help(pushmodel:"example") for an example.

@@@@see_also#Cross references
See also pushmodel(), modelinfo(), coefs(), secoefs(), contrast(),
'macros'.

====power()#probabilities,glm,anova
%%%%
power(noncen,ngrp,nrep,alpha [,design:"rbd"]), noncen >= 0, 0 <  alpha
  < 1, integers ngrp > 0 and nrep > 0; some or all arguments may be
  vectors
%%%%
@@@@usage#Usage
power(noncen,ngrp,nrep,alpha) computes the power of an F-test with
significance level alpha in a balanced one-way analysis of variance
(completely randomized design) for ngrp groups of size nrep (ngrp
treatments with nrep replications) with the n=1 noncentrality parameter
noncen.

The noncentrality parameter is noncen = sum(effects_i^2)/sigma^2 = the
sum of the squared treatment effects divided by the error variance.
This is sometimes called the "n=1 noncentrality parameter."  It differs
from the definition of the noncentrality parameter for power2() which
includes a factor of n.

power(noncen,ngrp,nrep,alpha,design:"rbd") computes power for a
randomized block design with nrep blocks and ngrp >= 2 treatments.

power(mu_a^2/sigma^2,1,n,alpha) computes the power against the
alternative hypothesis H_a: mu = mu_a of a single-sample two-tail t-test
of H_0: mu = 0 based on a sample of size n.  To compute the power of a
one-tail t-test, see cumstu:"non_central_t".

Some or all of the arguments of power may be vectors, in which case all
non-scalars must be the same length, which will also be the length of
the result.  For example, you can compute the power of randomized block
designs with 2 to 20 blocks, g treatments and noncentrality parameter 2
by
  Cmd> power(2.5, g, run(2,20), .05, design:"rbd")

This is exactly equivalent to
  Cmd> power2(run(2,20)*2.5, g-1, (g-1)*(run(2,20) - 1), .05)

If nrep was computed as samplesize(noncen,ngrp,alpha,pwr), the value of
power(noncen,ngrp, nrep,alpha) should be approximately equal to pwr, but
no smaller.

@@@@see_also#Cross references
See also power2() and samplesize().
@@@@______

====power2()#probabilities,glm,anova,regression
%%%%
power2(noncent2,numDF,denomDF,alpha), noncent2 >= 0, 0 <  alpha < 1,
  numDF >0, denomDF > 0; some or all arguments may be vectors
%%%%
@@@@usage#Usage
power2(noncen2,numDF,denomDF,alpha) computes the power for an F test
with numDF numerator degrees of freedom, denomDF denominator degrees of
freedom, a significance level of alpha, and noncentrality parameter
noncen2.

The noncentrality parameter noncen2 = sum(n_i*(effect_i)^2)/sigma^2,
where n_i and effect_i = mu_i - mu_all are the sample size and treatment
effect for group i, with mu_i = treatment i mean and mu_all =
sum(n_i*mu_i)/sum(n_i).

An more mathematical definition is
   noncen2 = numDF*(E[Numerator MS]/E[denominator MS] - 1);

Note that this differs from the n=1 non-centrality parameter expected by
power() which does not include a sample size.  For example, you will get
the same answers from
  Cmd> power2(nrep*noncen,ngrp-1,(nrep-1)*ngrp,alpha)
and
  Cmd> power(noncen,ngrp,nrep,alpha)

power2(n*mu_a^2/sigma^2,1,n-1,alpha) computes the power against the
alternative hypothesis H_a: mu = mu_a of a single-sample two-tail t-test
of H_0: mu = 0 based on a sample of size n.  To compute the power of a
one-tail t-test, see cumstu:"non_central_t".

Some or all of the arguments of power2() may be vectors, in which case
all non-scalars must be the same length, which will also be the length
of the result.  For example, you can compute a power as a function of
noncen2 by, say
   Cmd> power2(run(0,100)*1.2,10,20,.05)

If nrep was computed as samplesize(noncen,ngrp,alpha,pwr), the value of
power2(nrep*noncen,ngrp-1,(nrep-1)*ngrp,alpha) should be approximately
equal to pwr, but no smaller.

power2() is useful for computing the power of a test for a contrast, or
for interaction and related effects where the error degrees of freedom
are complicated functions of n.

@@@@see_also#Cross references
See also power() and samplesize().
@@@@______

====precedence#syntax,operations
%%%%
This topic has information on the precedence and grouping properities of
arithmetic, matrix, logical, comparison and bit operations.
%%%%
@@@@introduction#Introduction
Operators in MacAnova such as '+', '/', '<', '&&' and '<-' have rules of
association and precedence which determine the order in which they are
evaluated when used together.  As much as possible these mimic the rules
of ordinary algebra where they apply and for most purposes that is all
you need to know.  This topic summarizes the rules and includes a
precedence table for all operators.

@@@@association_properties_of_operators
                  Association properties of operators
A binary operator OP such as '+', '^' or '<=' either associates from
left to right, that is, x OP y OP z means (x OP y) OP z, or from right
to left, that is x OP y OP z means x OP (y OP z), or does not associate
at all, that is x OP y OP z is meaningless.

Binary arithmetic operators '+', '-', '*', '/', and '%%' associate from
left to right.  For example, x - y - z means (x - y) - z and x/y/z means
(x/y)/z.  See topic 'arithmetic'.

Exponentiation ('^' or '**') associates from right to left, that is
x^y^z is x^(y^z), not (x^y)^z.  See topic 'arithmetic'.

Binary logical operators '&&' and '||' associate from left to right.
For example, u && v && w means ((u && v) && w).  See topic 'logic'.

Matrix multiplication operators '%*%', '%c%' and '%C%' associate from
left to right.  For example, x %*% y %c% z %C% w is interpreted as
((x %*% y) %c% z) %C% w.  See topic 'matrices'.

The assignment operator '<-' and arithmetic assignment operators '<-+',
'<--', '<-*', '<-/', '<-^' and <-%%' (see topic 'arithmetic') also
associate from right to left.  That is, x <- y <- z is interpreted as x
<- (y <- z) and x <-+ y <-+ z is interpreted as x <-+ (y <-+ z).  See
topics 'assignment' and 'arithmetic'.

Comparison operators do not associate, that is, for example, x < y < z
has no meaning.  See topic 'logic'.

@@@@precedence_of_operators
                        Precedence of operators
"Precedence" has to do with the interpretations of expressions involving
more than one operator, for example 'x <- 3 + 4/5^2' which involves
operators '<-', '+', '/' and '^'.  Every operator has a numerical
precedence level.

The rule is simple: Operators with higher precedence are evaluated
before operators with lower precedence.

@@@@table_of_precedence_levels
                Table of precedence levels of operations
                    Precedence   Meaning
    x %| y               1       Bitwise Or (OR)
    x %^ y               2       Bitwise Exclusive Or (XOR)
    x %& y               3       Bitwise And (AND)
    %!x                  4       Bitwise Complement (COMPL)
    x || y               5       Logical Or
    x && y               6       Logical And
    !x                   7       Logical Not
    x == y               8       Equal or same
    x != y               8       Not equal or different
    x < y                8       Less than
    x <= y               8       Less than or equal
    x > y                8       Greater than
    x >= y               8       Greater than or equal
    x + y                9       Addition (sum of x and y)
    x - y                9       Subtraction (difference of x and y)
    x * y               10       Multiplication (product of x and y)
    x / y               10       Division (x divided by y)
    x %% y              10       Modular division (x - y*floor(x/y))
    x %*% y             11       x MatMult y
    x %c% y             11       transpose(x) MatMult y
    x %C% y             11       x MatMult transpose(y)
    -x                  12       Unary minus ((-1)*x)
    +x                  12       Unary plus ((+1)*x)
    x ^ y or x ** y     13       Exponentiation (x to the y-th power)
    x <- y            14 or 0    Assign value of y to x
    x <-+ y           14 or 0    x <- x + y
    x <-- y           14 or 0    x <- x - y
    x <-* y           14 or 0    x <- x * y
    x <-/ y           14 or 0    x <- x / y
    x <-^ y           14 or 0    x <- x ^ y
    x <-** y          14 or 0    x <- x ** y
    x <-%% y          14 or 0    x <- x %% y

In the above MatMult is ordinary matrix multiplication.

You may use parentheses to group terms and change the order of
evaluation.  Subexpressions within '(...)' or '{...}' are evaluated
before the bracketed terms are combined.

The dual levels 0 and 14 for the assignment operators reflect the fact
that they have lower precedence than any operator to their right and
higher precedence than any operator to their left.  For example, x <- y
+ z sets x to y + z while x + y <- z assigns z to y and then computes
the sum of x and the new value of y.  Similarly x <-+ y + z is
equivalent to x <-+ (y+z) and x + y <-+ z is equivalent to x + (y <-+
z).

@@@@examples#Examples
                                Examples
Expression  Interpretation   Value     Explanation
 30/5/2        (30/5)/2          3     / associates to left
 3^2^4         3^(2^4)       43046721  ^ associates to right
 4*3-2       (4*3) - 2    12 - 2 = 10  * has higher precedence than -
 3*2^4        3*(2^4)       3*16 = 48  ^ has higher precedence than *
 (3*2)^4                   6^4 = 1296  Parentheses change evaluation
                                       order
 -2^4          -(2^4)          -16     ^ has higher precedence than
                                       prefix -
 (-2)^4                         16     Parentheses change evaluation
                                       order
 3<2+4        3 < (2+4)    3 < 6 =  T  + has higher precedence than <
 T||F&&F      T||(F&&F)      T||F = T  && has higher precedence than ||
 !T||T         (!T)||T       F||T = T  ! has higher precedence than ||
 !(T||T)                     !T = F    Parentheses change evaluation
                                       order

@@@@see_also#Cross references
See topic 'bit_ops' for examples of how precedence and parentheses
affect the order of evaluation of operations '%&', '%|', '%^' and '%!'.
@@@@______

====predtable()#glm,anova
%%%%
predtable([keyword phrases] [,silent:T]) or predtable(Term [,keyword
  phrases] [,silent:T]), Term a CHARACTER scalar of the form "A.B. ...",
  where A, B are factors in current GLM model, or term:k, where k is a
  positive integer, and allowed keyword phrases seest:T, sepred:T,
  estimate:F, wtdmeans:T or x:values as for glmtable().
%%%%
@@@@usage#Usage
predtable() computes a table of fitted values (estimated cell expected
values) based on the computations of the most recent GLM (generalized
linear or linear model) command such as anova() or poisson().  The table
has a dimension for each factor in the model, in the order the variables
appear in the model.  It is an error if there are no factors in the
model. See glmtable() for a somewhat more general function.

predtable(seest:T) does the same, except the result is a structure with
two components, 'estimate' and 'SEest' containing the table of fitted
values and their standard errors.

predtable(sepred:T) does the same, except the structure result has
components 'estimate' and 'SEpred', where SEpred contains standard
errors of prediction (usually sqrt(SEest^2 + MSE)) for each cell.

You can use both 'sepred:T' and 'seest:T' together, and can suppress the
table of estimates with 'estimate:F'.

predtable(Term) returns an estimated table of marginal means where the
margins are specified by Term.

Term must be a quoted string or CHARACTER scalar of the form
"Name1.Name2.Name3....", where Name1, Name2, ... are names of factors in
the current GLM model.

When there are k factor names in Term, the value of predtable() is an
array with k dimensions (vector if k = 1, matrix if k = 2), with the
dimensions ordered in the same order as in Term, not the order they
appear in the model if that is different.

predtable(Term, seest:T) does the same, but the result is a structure
with components 'estimate' and 'SEest', where SEest contains the
standard errors of the estimated marginal means.

You cannot use 'sepred:T' with Term when Term specifies a marginal
table, that is, Term does not include all factors in the model.

predtable(term:k [,seest:T]) is essentially equivalent to
predtable(TERMNAMES[k] [,seest:T]), computing the marginal table
matching term k in the model.

You cannot use predtable(Term [,...]) after anova() with a balanced
design unless Term includes all the factors in the model.

@@@@examples#Examples
Examples:
  Cmd> anova("y=a+b") # two-way ANOVA
  Model used is y=a+b
  WARNING: summaries are sequential
                  DF          SS          MS
  CONSTANT         1    0.021986    0.021986
  a                2      12.082       6.041
  b                3      12.419      4.1397
  ERROR1          24      39.977      1.6657

  Cmd> predtable() # estimates of cell means
  (1,1)      1.0316     0.23603    -0.43016     -1.3688
  (2,1)     0.98354     0.18795    -0.47824     -1.4169
  (3,1)      2.1081      1.3125     0.64631    -0.29238

  Cmd> predtable(seest:T,sepred:T) #cell mean estimates and SE's
  component: estimate
  (1,1)      1.0316     0.23603    -0.43016     -1.3688
  (2,1)     0.98354     0.18795    -0.47824     -1.4169
  (3,1)      2.1081      1.3125     0.64631    -0.29238
  component: SEest           [SE of estimated cell mean]
  (1,1)      1.2906     0.48563     0.58437     0.57713
  (2,1)      1.4245     0.57943      0.4888     0.57981
  (3,1)      1.4247      0.4894     0.56226     0.66824
  component: SEpred          [SE of prediction for cell]
  (1,1)      1.8252       1.379      1.4168      1.4138
  (2,1)      1.9222      1.4147      1.3801      1.4149
  (3,1)      1.9223      1.3803      1.4078      1.4534

  Cmd> predtable(a,seest:T) # marginal mean estimate and SE's
  component: estimate
  (1)    -0.13284    -0.18092     0.94363
  component: SEest
  (1)     0.44971      0.5415     0.56229

  Cmd> predtable(term:2) #second term is a
  (1)    -0.13284    -0.18092     0.94363

@@@@silent_keyword#Keyword 'silent'
predtable(silent:T) and predtable(Term, silent:T) do the same, except
that certain advisory messages are suppressed.  'silent:T' can be used
with any other keywords.  The default value of 'silent' is False unless
the value of option' 'warnings' is False.

@@@@behavior_with_variates
             Behavior when there are variates in the model
The fitted values are by default computed with each variate set to its
unweighted mean value and thus are what are sometimes called the
covariate adjusted cell means.

predtable(wtdmeans:T [,...]) does the same except it adjusts cell fitted
values to the weighted means of the variates.  You can use wtdmeans:T
only when there are variates and when the previous GLM command used
weighted OLS (anova() or manova()).  This option would be probably
appropriate when the weights were proportional to sample sizes.

predtable(x:Vals [,...]), where Vals is a REAL vector with length = the
number of variates (non-factors) in the model, does the same
computation, except it uses the elements of Vals instead of unweighted
or weighted variate means.  This option allows you to estimate cell
means that are adjusted to any level of the covariates.  Use of x:Vals
is an error if there are no variates in the current GLM model.

@@@@relationship_to_glmtable#Relationship to glmtable()
predtable() and predtable(Term) are equivalent to glmtable(seest:F) and
glmtable(Term, seest:F).  Usage of keywords 'seest' and 'sepred' is the
same as for glmtable().

@@@@binomial_responses#Binomial responses
For GLM functions involving a binomial response variable (logistic(),
probit(), glmfit() with dist:"binomial"), the values computed are the
estimated probabilities p of "success" associated with each cell.

In this case, you can also use keyword phrase n:N, where N is a REAL
variable, to specify the number of trials for each cell.  N can be a
scalar, a vector whose length matches the size of the table, or a matrix
or array whose dimensions match those of the table.  The resulting table
is a table of N*p.

Example:
  Cmd> logistic("y=a+b",n:100); predtable(n:100)

@@@@caveat_about_empty_cells#Caveat about empty cells
Caution: When the marginal table for any term in the model contains
empty cells, especially when a factor is nested in another with
different numbers of levels, the estimated means may not be what you
want.

@@@@behavior_with_non_linear_model#Behavior with non linear model
After fitting a non-linear model by logistic(), probit(), poisson(), or
glmfit(), when Term doesn't contain all the factors in the model,
predtable(Term) first computes the estimated marginal table in the
linear scale (logit, probit, or log) and then transforms it back into
the scale of the response.  This means that the computed marginal table
is not the marginal means of the fitted table.  For example, if b is a
factor with 3 levels, after logistic("y=a*b", n:40),
sum(predtable("a.b"))/3 is not the same as predtable("b").

@@@@limitation#Limitation
When keyword phrase coefs:F was an argument on the most recent GLM
command, predtable() is not available.

@@@@see_also#Cross references
See also topics anova(), anovapred(), glmpred(), glmtable(), regpred(),
modelinfo(), popmodel(), pushmodel(), 'glm'.
@@@@______

====primefactors()#general
%%%%
primefactors(n [, max:T]), n an integer scalar or vector
%%%%
@@@@usage#Usage
primefactors(n), where n is a positive integer < 2^52 =
4503599627370496, returns a vector containing the prime factors of n,
possibly with repetitions.

When n is a vector of positive integers <= 999999999999 = 10^12 - 1,
primefactors(n) returns a structure with length(n) components.
Component i is a vector containing the prime factors of n[i] and having
the numeric value of n[i] as its name.  The reason for the smaller range
of permissible values is because a component name can have at most 12
characters.  Note:  Because the component names are numeric and not
alphabetic, you must use a subscript to extract a component.

primefactors(n,max:T), where n is a positive integer scalar or vector
with n[i] < 2^52 = 4503599627370496, returns an integer vector of the
same length as n containing the maximum prime factors of each element of
n.

@@@@examples#Examples
Examples:
  Cmd> primefactors(64094231)
  (1)          641        99991

  Cmd> stuff <- primefactors(vector(3,15,64094231)); stuff
  component: 3
  (1)            3
  component: 15
  (1)            3            5
  component: 64094231
  (1)          641        99991

  Cmd> stuff[3] # stuff$64094231 is illegal
  (1)          641        99991

  Cmd> stuff[compnames(stuff) == "64094231"]
  (1)          641        99991

  Cmd> primefactors(64094231, max:T)
  (1)        99991

@@@@see_also#Cross references
See also goodfactors().
@@@@______

====print()#output,missing values
%%%%
print(a, b, ...[,format:Fmt or nsig:m, header:F, labels:F, notes:T,\
  width:w, height:h, macroname:T, missing:missStr, name:setName]\
  [, file:fileName [,new:T]]]), Fmt, missStr, fileName, setName
  CHARACTER scalars, m > 0, w >= 30, h >= 12 integers
%%%%
@@@@usage#Usage
print(a,b, ...) prints objects (variables, expressions, macros) a, b,
....  By default the names 'a', 'b', ... are printed.

By default, print() formats REAL items using the format identified by
'format' on getoptions() output.  This normally is floating point with 5
significant digits.  Type help(options:"format") for details.

  Cmd> print(PI,sqrt(2)*run(5))
  PI:
  (1)      3.1416
  VECTOR:
  (1)      1.4142      2.8284      4.2426      5.6569      7.0711

print() encloses macros and the elements of CHARACTER variables in
quotes ("").  Any internal quotes are escaped with '\' (for example
"\"Hello\"") and non-printable characters are printed as escaped octal
integers (for example, "\033" or "\177").

  Cmd> a <- vector("Charlie","Dog"); print(a)
  a:
  (1) "Charlie"
  (2) "Dog"

print(Message), where Message is a single quoted string or CHARACTER
scalar, prints Message just as it is, without enclosing quotes and
without any internal quotes and non-printable characters escaped.

  Cmd> print("Charlie is a good dog!")
  Charlie is a good dog!

print(Message, macroname:T) does the same, except that when executed in
a macro, " in macro XXXX" is appended to Message.  This is useful for
printing messages in a macro.

You can modify the behavior of print using keywords 'format', 'nsig',
'missing', 'zero', 'labels', 'header', and 'notes'.  See below.

When either of keywords 'format' or 'nsig' are used, print() is
identical to write() with the same arguments.

print() is particularly useful in macros and inside {...}.

@@@@printing_to_a_file#Printing to a file
print(a,b,...,file:FileName [,new:T]) where FileName is a quoted string
or CHARACTER variable, writes the output to the specified file rather
than to the screen.  With 'new:T', any information in the file is
discarded before writing.  Without 'new:T', output is appended to the
end of the file.

When FileName is the variable CONSOLE or a CHARACTER variable whose
value is "CONSOLE", the output is written to the screen or output window
rather than to a file.

@@@@use_of_keywords#Use of keywords
Keywords 'nsig', 'format', 'name', 'header', 'labels', 'notes',
'missing' and 'zero' are all recognized and can appear more than once.
They affect the printing of objects that follow them, until they are
changed except that a value for 'name' is used only once.  Any of them
that follow all items to be printed are treated as coming before all
items.  For example,
  Cmd> print(x,nsig:5,y,nsig:10)
and
  Cmd> print(nsig:10,x, nsig:5,y)
are equivalent.

Keywords 'file' and 'new' can appear only once, anywhere in the argument
list.

@@@@nsig_and_format_keywords#Keywords 'nsig' and 'format'
print(nsig:d,a,b,...) or print(a,b,...,nsig:d) prints numbers with d
significant digits in floating point format with width d+7.

  Cmd> print(PI,nsig:7)
  PI:
  (1)       3.141593

print(format:Fmt,a,b,...) or print(a,b,...,format:Fmt), where Fmt is a
quoted string or CHARACTER variable, prints numbers according to
specifications given in Fmt.

Fmt must be of the form "w.df" or "fw.d" (fixed point) or "w.dg" "gw.d"
(floating point) where w (field width) and d (decimals or significant
digits) are integers, for example "6.3f" or "g15.7".  See below for
details.

  Cmd> print(1000*PI,format:"12.6f") # fixed with 6 decimals
  NUMBER:
  (1)  3141.592654

@@@@name_header_keywords#Name header keywords
print(name:Name, a, b,... ) prints a with the name specified by
quoted string or CHARACTER scalar Name on the header.

Name can be of unlimited length aiding the creation of informative
output.

  Cmd> print(3*log(640320)/sqrt(163), nsig:17,\
     name:"3*log(640320)/sqrt(163) is a good approximation to pi")
  3*log(640320)/sqrt(163) is a good approximation to pi:
  (1)       3.1415926535897931

The value of 'name' is used for only one output variable; however, you
can have several instances of name:Name, each affecting the next
variable output.

Alternatively, if the name is a legal MacAnova variable name no more
than 10 characters long you can use a keyword to specify the name.  For
example print(name:"Residuals", r) and print(Residuals:r) are
equivalent.

print(header:F,x,header:T,y,...,) prints x without and y with an
identifying name.

  Cmd> print(PI,header:F)
  (1)      3.1416

@@@@width_and_height_keywords#Keywords 'width' and 'height'
print(a,b,...,width:w) temporarily sets option 'width' to w, an integer
>= 30. This affects how many items are printed per line.

print(a,b,...,height:h) temporarily set option 'height' to h, an integer
>= 12.  This affects the number of lines in any graphs being printed as
"dumb" plots and how often output will be paused in non-windowed
versions.

@@@@labels_keyword#Keyword 'labels'
By default, print() prints coordinate labels, if they exist, or the
index or indices of the first element in each line otherwise.  See topic
'labels'.  Use of 'labels:F' suppresses printing of labels or indices.
A later 'labels:T' re-enables such printing.

  Cmd> print(PI,labels:F) # leading index (1) suppressed
  PI:
        3.1416

@@@@notes_keyword#Keyword 'notes'
Keyword phrase 'notes:T' directs that any notes attached to variables
are printed above the values.

  Cmd> Pi <- vector(PI,labels:"pi",notes:"Copy of variable PI")

  Cmd> print(Pi,notes:T)
  Pi:
  Copy of variable PI
            pi
                  3.1416

See topic 'notes' for details on attached notes.

@@@@missing_keyword#Keyword 'missing'
print(missing:MissStr1,a,b,...), where MissStr is a quoted string or
CHARACTER variable such as "?" or "NA", specifies that all missing
values are to be printed using MissStr.  If 'missing' is not used,
missing values are printed as "MISSING" (or using a different default if
you changed it by setoptions(); type help(options:"missing")).  Note
that this differs from the use of 'missing' on matprint() and matwrite()
for which the value must be a REAL scalar.

  Cmd> print(vector(PI,?,run(3)),missing:"NA")
  VECTOR:
  (1)      3.1416          NA           1           2           3

print(x,file:FileName,new:T,header:F,labels:F,missing:"?") writes x to
the file in a form that can be read by vecread().

@@@@zero_keyword#Keyword 'zero'
print(zero:ZeroStr,a,b,...), where ZeroStr is a quoted string or
CHARACTER variable such as " ", "0" or "ZERO" specifies that zero values
are to be printed using ZeroStr.  If 'zero' is not used, zero values are
printed using the same format as other numbers.

  Cmd> print(PI*run(-2,2),zero:"Zero")
  VECTOR:
  (1)     -6.2832     -3.1416        Zero      3.1416      6.2832

@@@@details_on_format_keyword
                   Details on value of 'format' keyword
If Fmt is "w.df" or "fw.d" (fixed point), or "w.dg" or "gw.d" (floating
point), integer w specifies a field width of at least w characters.  For
fixed point format, integer d is the number of digits that will follow
the decimal point.  For floating point format, d is the number of
significant digits printed.  If w is omitted (".3f" / "f.3" or ".7g" /
"g.7"), it is implicitly set to d+7 ("10.3f"/ "f10.3" or "14.7g" /
"g14.7").  If w > 27, width = 27 is assumed and if d > 20, digits = 20
is assumed.

With fixed point output, trailing zeros are kept; for floating point
output they are trimmed off.  For example, 10.30 is printed as
'10.30000' with "8.5f" or "f8.5" format and as '10.3' with "8.5g" or
"g8.5" format.

For floating point output, exponential form, 9.3e+07 for example, is
used if required to represent the number.

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

@@@@examples#Examples
Examples:
  print(nsig:5,a), print(format:"12.5g",a), and print(a,nsig:5),
are equivalent.
  print(nsig:5,file:"myfile",a,new:T)
writes a to file "myfile", starting fresh.

  Cmd> print("Quoted because > 1 argument",vector("a","Escaped\1\2"))
  STRING:
  (1) "Quoted because > 1 argument"
  VECTOR:
  (1) "a"
  (2) "Escaped\001\002"

  Cmd> print("Not quoted because only 1 argument")
  Not quoted because only 1 argument

Keywords that are not otherwised recognized are used to label output.
Keywords may have no more than 10 characters.

  Cmd> print(run(5)) # no labeling keyword
  VECTOR:
  (1)           1           2           3           4           5

  Cmd> print(one2five:run(5)) 3 with labelling keyword
  one2five:
  (1)           1           2           3           4           5

@@@@see_also#Cross references
See also topics 'options', write(), matprint(), matwrite(), paste(),
error().
@@@@______

====printoptions()#control,general
%%%%
printoptions()
printoptions(option1:T [,option2:T ...]), where option1,
  option2, ... are option names
%%%%
@@@@usage#Usage
printoptions(), with no arguments, prints the values of all options in
alphabetical order and in a more concise format than is used by
print(getoptions()).

printoptions(option1:T [,option2:T ...]) prints the values of the named
options in a concise format.  option1, option2, ... must be legal options.

@@@@examples#Examples
Examples:
  Cmd> printoptions(format:T,minpvalue:T,seeds:T)
  format = "11.5g"
  minpvalue = 1e-08
  seeds = 518084227 1327950740

  Cmd> printoptions()
  angles = "cycles"
  batchecho = T
  dumbplot = F
  . . . . .
  . . . . .
  warnings = T
  wformat = "16.9g"
  width = 72

@@@@see_also#Cross references
See also getoptions(), setoptions(), 'options'.

====probit()#glm,regression,categorical data
%%%%
probit([Model], n:Denom [, print:F or silent:T, incr:T, offsets:vec,\
  pvals:T, maxiter:m, epsilon:eps, coefs:F]), Denom REAL scalar or
  vector > 0, vec a REAL vector, m an integer > 0, eps REAL > 0
%%%%
@@@@usage#Usage
probit(Model,n:Denom) computes a probit regression fit of the model
specified in the CHARACTER variable Model.  If y is the response
variable in the model it must be a REAL vector with y[i] >= 0.  Denom
must either be an REAL scalar >= max(y) or a REAL vector of the same
length as y with Denom[i] >= y[i].  Estimation is by maximum likelihood
on the assumption that y[i] is binomial with Denom[i] trials (Denom
trials for scalar DENOM).  If any y[i] or n[i] is not an integer a
warning message is printed.

To get the coefficients for a classic probit analysis, you should
increase the estimated constant by 5.

probit(Model,n:Denom,...) is equivalent to glmfit(Model,n:Denom,
dist:"binomial", link:"probit",...).

See topic 'models' for information on specifying Model.

@@@@side_effect_variables_created#Side effect variables created
probit() sets the side effect variables RESIDUALS, WTDRESIDUALS, SS, DF,
HII, DEPVNAME, TERMNAMES, and STRMODEL.  See topic 'glm'.  Without
keyword phrase 'inc:T' (see below), TERMNAMES has value vector("","",
...,"Overall model","ERROR1"), DF has value vector(0,0,...,ModelDF,
ErrorDF) and SS has value vector(0,0,...,ModelDeviance,ErrorDeviance).

@@@@analysis_of_deviance#Analysis of deviance
If, say, Model is "y=x1+x2", an iterative algorithm is used to predict
invnor(E[y/Denom]) = probit(E[y/Denom]) - 5 as a linear function of x1
and x2.  A two line Analysis of Deviance table is printed.  Line 1 is
the difference 2*L(1) - 2*L(0), where L(0) is the log likelihood for a
model with all coefficients 0 (all probabilities = 0.5) and L(1) is the
maximized log likelihood for the model fit.  Line 2 is 2*L(2) - 2*L(1)
where L(2) is the maximized log likelihood under a model fitting one
parameter for every y[i].  Under appropriate assumptions, the latter can
be used to test the goodness of fit of the model using a chi-squared
test.

@@@@incremental_fitting#Incremental fitting
probit(Model,n:Denom,inc:T) computes the full probit model and all
partial models -- only a constant term, the constant and the first term,
and so on.  It prints an Analysis of Deviance table, with one line for
each term, representing a difference 2*L(i) - 2*L(i-1) where L(i) is the
maximumized log likely for a model including terms 1 through i, plus the
deviance of the complete model labeled as "ERROR1".  Each line except
the last can be used in a chi-squared test to test the significance of
the term on the assumption that the true model includes no later terms.

@@@@omitting_model#Omitting model
If you omit Model (probit(,n:Denom ...)), the model from the most recent
GLM command such as poisson() or anova(), or the model in CHARACTER
variable STRMODEL is assumed.

@@@@algorithm#Algorithm
Computations are carried out using iteratively reweighted least squares.

@@@@problimit_warning#Problimit warning
If you get a warning message similar to the following
   WARNING: problimit = 1e-08 was hit by probit() at least once
it usually indicates either the presence of an extreme outlier or a best
fitting model in which many of the probabilities are almost exactly 0 or
1.  The latter case may not represent any problem, since the fitted
probabilities at these points will be 1e-8 or 1 - e-8.  You can try
reducing the threshold using keyword 'problimit' (see below), but you
will probably just get the message again.

@@@@keywords
                     Other keyword phrases
Keyword phrase  Default  Meaning
  maxiter:m       50     Positive integer m is the maximum number of
                         iterations that will be allowed in fitting

  epsilon:eps    1e-6    Small positive REAL specifying relative error
                         in objective function (2*log likelihood)
                         required to end iteration

  problimit:small 1e-8   Iteration is restricted so that no fitted
                         probabilities are < small or > 1 - small. Value
                         of small must be between 1e-15 and 0.0001.

  offsets:OffVec  none   Causes model to be fit to probit(p) to be
                         1*Offvec + Model, where OffVec is a REAL vector
                         the same length as response y.  Note OffVec is
                         in probit units.

See topic 'glm_keys' for information on keyword phrases print:F,
silent:T, coefs:F

The default value for pvals can be changed by setoptions(pvals:T).  See
topics setoptions(), 'options'.

@@@@examples_on_use_of_offsets#Examples on use of 'offsets'
  Cmd> probit("y=x", n:15, offsets:3*x, inc:T, pvals:T)
The P value associated with x can be used to test the hypothesis H0:
beta1 = 3 in the model invnor(p) = beta0 + beta1*x.

  Cmd> probit("y=1", n:20, offsets:rep(invnor(.25),length(y)),\
       inc:T, pvals:T)
The P value associated with the CONSTANT term can be used to test H0:
p = .25, assuming y contains a random sample from a binomial
distribution with n = 20.
@@@@______

====prod()#summary statistics
%%%%
prod(x [,squeeze:T] [,silent:T,undefval:U]), x REAL or LOGICAL or a
  structure with REAL or LOGICAL components, U a REAL scalar
prod(x, dimensions:J [,squeeze:T] [,silent:T,undefval:U]), vector of
  positive integers J
prod(x, margins:K [,squeeze:F] [,silent:T,undefval:U]), vector of
  positive integers K
prod(x1,x2,... [,silent:T,undefval:U]), x1, x2, ... REAL or LOGICAL
  vectors, all the same type.
%%%%
@@@@usage#Usage
prod(x) computes the product of the elements of a REAL or LOGICAL vector
x.

If x is LOGICAL, True is interpreted as 1 and False as 0 and hence
prod(x) has value 1 if all elements of x are True and 0 if any is False.

If x is a m by n matrix, prod(x) computes a row vector (1 by n matrix)
consisting of the product of the elements in each column of x.

If x is an array with dimensions n1, n2, n3, ..., y <- prod(x) computes
an array with dimensions 1, n2, n3, ... such that y[1,j,k,...] =
prod(x[i,j,k,...], i=1,...,n1).  This is consistent with what happens
when x is a matrix.  Note: MacAnova3.35 and earlier produced a result
with dimensions n2, n3, ... .

prod(x, squeeze:T) does the same, except the first dimension of the
result (of length 1) is squeezed out unless the result is a scalar.  In
particular, if x is a matrix, prod(x,squeeze:T) will be identical to
vector(prod(x)), and if x is an array, prod(x,squeeze:T) will be
identical to array(prod(x),dim(x)[-1]).

prod(NULL) is NULL.

prod(a,b,c,...) is equivalent to prod(vector(a,b,c,...)) if a, b, c,
... are all vectors.  They must all have the same type, REAL or LOGICAL
or be NULL.  prod(NULL, NULL, ..., NULL) is NULL.

prod(x, silent:T) or prod(a,b,c,...,silent:T) does the same but
suppresses warning messages about MISSING values or overflows.

If all the elements of a vector x are MISSING, prod(x) is 1.0.

prod(x, undefval:U), where U is a REAL scalar does the same, except the
returned value is U when all the elements of x are MISSING.

@@@@structure_argument#Structure argument
If x is a structure, prod(x) computes a structure, each of whose
components is prod() applied to that component of x.

@@@@dimensions_keyword#Keyword 'dimensions'
prod(x, dimensions:J [,squeeze:T] [,silent:T] [undefval:U]) computes
products over the dimensions in J = vector(j1,j2,...,jn) where j1, ...,
jn are distinct positive integers <= ndims(x).  Without 'squeeze:T', the
result has the same number of dimensions as x, with dimensions j1, j2,
..., jn of length 1.  With 'squeeze:T', these dimensions are removed
from the result.  The order of j1, j2, ... is ignored.

It is an error if max(J) > ndims(x) or if there are duplicate elements
in J.

For example, if x is a matrix, prod(x, dimensions:2) computes the row
products as a nrows(x) by 1 matrix and prod(x, dimensions:2,squeeze:T)
computes them as a one dimensional vector.

@@@@margins_keyword#Keyword 'margins'
prod(x, margins:K [,squeeze:F] [,silent:T] [undefval:U]) computes
products over the dimensions not in K = vector(k1, k2, ..., km), where
k1, ..., km are distinct positive integers <= ndims(x).  This computes
marginal products for the margins specified in K.

Without 'squeeze:F', only the dimensions in K are retained in the
result.  Otherwise the other dimensions are retained but have length 1.
This is opposite from the default with 'dimensions:J'.

It is an error if max(K) > ndims(x) or if there are duplicate elements
in K.

@@@@example#Example
Examples:
  Cmd> x # matrix with labels
              B1          B2
  A1          18          15
  A2          17          26
  A3          18          19

  Cmd> prod(x) # products down columns
               B1          B2
  (1)        5508        7410

  Cmd> prod(x)/x # elements in row are products of other rows of x
              B1          B2
  A1         306         494
  A2         324         285
  A3         306         390

  Cmd> prod(x,dimensions:2) # products accross rows
             (1)
  A1         270
  A2         442
  A3         342

  Cmd> prod(x,margins:1) # same as a vector
            A1          A2          A3
           270         442         342

@@@@see_also#Cross references
See also topics sum(), 'NULL'.
@@@@______

====propinterval()#probabilities,descriptive statistics,comparisons
%%%%
propinterval(x[,y],cover:fraction,[options])
propinterval(s1,n1[,s2,n2],cover:fraction,[options])
options can include upperb:T or lowerb:T, plus4:T|F.
%%%%
propinterval() computes a z-confidence interval for a population
proportion or difference of population proportions, depending on
whether data for one or two variables are given as arguments.  By
default, propinterval() computes a two-sided interval, but you may
choose one-sided alternatives by using one of lowerb:T or upperb:T.
Arguments may be either vectors of 0/1 data, or may be counts of
successes and numbers of trials.  

You specify the coverage rate via cover:value. 

You may specify the Agresti "add 4" procedure via plus4:T.  This
will add 2 successes and two failures (split among the two samples
for two-sample tests).

The output is a vector containing the estimate and interval bounds.

====proptest()#probabilities,descriptive statistics,comparisons
%%%%
proptest(x[,y],null:val,[upper:T or lower:T,contcor:T|F,pool:T|F])
proptest(s1,n1[,s2,n2],null:val,[upper:T or lower:T,contcor:T|F,pool:T|F])
%%%%
proptest() performs a one- or two-sample z-test for proportions,
depending on whether data for one or two variables are given as
arguments.  Arguments may be either vectors of 0/1 data, or may be
counts of successes and numbers of trials.  By default there is
a two-tailed alternative, but you may choose one-sided alternatives
by using one of lowertail:T or uppertail:T.

You specify the null value via null:value.  For a two-sample test,
only null:0 is allowed.

Use of contcor:T will cause the p-value to be calculated with a
continuity correction.

For a two-sample test, you may specify that the variances be pooled
or unpooled via pool:T or pool:F.

The output is a vector containing the z-statistic and the p-value.


====pushmodel()#anova,glm,multivariate analysis,regression,residuals
%%%%
pushmodel()
pushmodel(canpush:T)
%%%%
@@@@introduction#Introduction
All GLM commands except screen(), for example regress() and anova(),
retain information (GLM information) internally for use by certain
functions such as coefs() and modelinfo() that provide results from the
most recent GLM command.  When a GLM command is run, information from
the previous GLM command, if any, is replaced.  When the GLM command is
in a macro, this may confuse the user who may expect that coefs(), say,
gives the same answer after the macro is used as before.

Commands pushmodel() and popmodel() allow a macro to save and restore
the current GLM information.

pushmodel() saves the current GLM information so that it can
subsequently be restored by popmodel().  Until a new GLM command has
been run or GLM information has been restored by popmodel(), there is no
GLM information available to commands such as secoefs() and modelinfo().

After the next prompt following the use of pushmodel(), the active model
before the first use of pushmodel() is restored (equivalent to an
automatic execution of popmodel(all:T)).

pushmodel() and popmodel() are intended to be used in macros.  A macro
can run pushmodel() before a GLM command and then run popmodel() before
finishing to ensure that the current GLM information is not changed.  Of
course, if the purpose of the macro is to change the information, it
should not use pushmodel() and popmodel().

The default maximum number of sets of GLM information that can be saved
is 2 (0 in limited memory DOS version).  On versions allowing command
line arguments you can change the default by '-savemodels N' where N >=
0 is an integer.  See 'launching'.

@@@@usage#Usage
pushmodel() saves the current GLM information from the most recent GLM
command.  Until a subsequent GLM command or popmodel() has been run, or
a new prompt is printed, no model information is available for retrieval
by functions like secoefs() and modelinfo().  You can use popmodel() to
restore the saved GLM information.

It is an error if there is no current model to save or you have already
saved the maximum number of models (default is 2).

pushmodel(canpush:T) returns True if there is current GLM information to
save and a place to put it and False otherwise.  No GLM information is
saved and the current GLM information, if any, is not changed.

@@@@example#Example
Here is the text of a macro aov() which returns the SS and DF of an
analysis of variance without changing the current GLM information or
side effect variables, if any.

  if (pushmodel(canpush:T)){pushmodel()}
  anova($1, silent:T)
  @result <- structure(SS,DF)
  if (popmodel(canpop:T)){popmodel()}
  @result #will be returned as value of the macro

This might be used as follows"

  Cmd> aov("y=a") # this won't change GLM info or side effect variables
  component: SS
      CONSTANT           a      ERROR1
        3.8646    0.021371      4.8536
  component: DF
      CONSTANT           a      ERROR1
             1           2           7

@@@@see_also#Cross references
See also popmodel(), modelinfo(), coefs(), secoefs(), contrast(),
'macros'.

====putascii()#output,character variables
%%%%
putascii(vec [,keep:T]), vec a vector of integers > 0 and <= 255
putascii(vec, file:fileName [, new:T])
%%%%
@@@@usage#Usage
putascii(Vec) prints the characters corresponding to the elements of the
vector Vec, considered as ASCII codes.  All the codes must be integers
between 1 and 255, inclusive.  For example, putascii(run(64,126)) prints
@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~

putascii(Vec1,Vec2,...) is equivalent to putascii(vector(Vec1,Vec2,
...)), if Vec1, ..., are REAL vectors.

The primary use of putascii() is to send control sequences to a
terminal.  See macro vt() for an example of its use.  On all machines,
any leading 7's are explicitly translated to beeps or bells.  For
example
  Cmd> putascii(vector(7,7,7,69,82,82,79,82))
rings the bell three times and prints ERROR.

getascii() is almost an inverse to putascii(), translating CHARACTER
variables to a vector of integers.

@@@@writing_to_a_file#Writing to a file
putascii(Vec,file:FileName [,new:T]) or putascii(Vec1, Vec2, ...,
file:FileName [,new:T]), where FileName is a CHARACTER variable or
quoted string, writes the ASCII codes on file FileName.  If new:T is an
argument, any information in the file will be destroyed; otherwise the
codes are added at the end of the file.

@@@@keep_keyword#Keyword 'keep'
putascii(Vec,keep:T) or putascii(Vec1,Vec2,...,keep:T) returns a
CHARACTER variable whose characters have the ASCII codes.  For example,
putascii(run(4,8), keep:T) has value "\004\005\006\007\010".  Use of
new:T with file:FileName is illegal.

@@@@difference_from_makesymbols#Difference from makesymbols()
The usage putascii(Vec, keep:T) is somewhat similar to makesymbols(Vec,
keep:T) since both translate ASCII codes to characters.  The difference
is that putascii() returns a CHARACTER scalar with length(Vec)
characters while makesymbols() returns a CHARACTER vector of
length(Vec), with each element a single character.  See makesymbols()
for details.

@@@@see_also#Cross references
See also print(), write().
@@@@______

====qr()#matrix algebra
%%%%
qr(x [,pivot:T, ronly:T]), x a REAL matrix
%%%%
@@@@usage#Usage
qr(x) computes the elements of a QR decomposition of matrix x

The value returned is structure(qr:Qr, qraux:Qraux), where Qr is a REAL
vector of length P and Qraux is a REAL n by p matrix, as computed by
Linpack subroutine dqrdc.  The elements of Qr on and above the diagonal
constitute the upper triangular matrix R of the QR decomposition, and
the remaining elements, together with the elements of Qraux contain
enough information to compute Q.  No pivoting is performed with this
usage of qr().

qr(x,pivot:T) or simply qr(x,T) does the same computation, with possible
reordering of columns.  The result is a structure(qr:Qr,qraux:Qraux,
pivot:Pivot), where Pivot is a vector of length p containing the column
numbers in x corresponding to the successive columns of q and r.

qr(x,ronly:T) returns a p by p upper triangular matrix consisting of the
R matrix in the QR decomposition, computed without pivoting.  For
example, both parts of the QR decomposition can be computed by
  Cmd> R <- qr(x,ronly:T) ; Q <- x %/% R # x %*% solve(R)

The columns of Q are orthogonal and x - Q %*% R will be zero except for
rounding error.

@@@@macro_qrdcomp#Macro qrdcomp()
An alternative way to get the full QR decomposition is by macro
qrdcomp() in macro file math.mac which uses the information in Qraux.
Type help(qrdcomp) for details.

@@@@see_also#Cross references
See also cholesky().
@@@@______

====quitting#general
%%%%
quit  or  bye  or  end  or  stop  or  exit
quit(F) or bye(F) or end(F) or stop(F) or exit(F)
%%%%
@@@@usage#Usage
To terminate a MacAnova run, type 'quit'.  On a windowed version, 
you will be asked if you want to save the workspace and any
command/output windows.

quit() or quit(T) has the same effect as 'quit'.

quit(F) means you want to quit unconditionally with no opportunity to
save the workspace or windows.  On a version without Windows, it is no
different from quit(T).

It is an error for quit to be part of a compound command (enclosed in
{...}) or for there to be anything other than a comment starting with
'#' after it on the command line.

'stop', 'end', 'bye' and 'exit' mean the same as 'quit'.

@@@@example#Example
Example:
  Cmd> quit  # or bye or stop() or end(T), etc.

@@@@quitting_in_windowed_versions#Quitting in windowed versions
In a windowed version, you can also select Quit on the File Menu. 
You will be asked whether you wish to save the workspace or the
command/output window(s).  On Mac OS 9, if you hold down the Option
key while selecting Quit or hitting Return after typing 'quit', you
quit unconditionally without a chance to save files.

@@@@see_also#Cross references
See also topic 'launching'.
@@@@______

====rank()#ordering
%%%%
rank(x [ ,down:T, ties:"ignore" or "average" or "minimum"]), x REAL or
  CHARACTER or a structure with all REAL or all CHARACTER components.
%%%%
@@@@usage#Usage
rank(x) computes the ranks of the data in variable x, the minimum value
being assigned rank 1.  In case of ties, the rank corresponding to the
average of the ranks for the tied cases is computed.  x can be REAL or
CHARACTER.

When x is CHARACTER, x[i] is considered greater than x[j] if x[i]
follows x[j] in alphabetical order using the ASCII collating sequence.
See sort() for the explicit ordering of characters.

rank(x,down:T) does the same except that the data are ranked in
decreasing order, with rank 1 assigned to the maximum element.

rank(x,ties:Method) or rank(x,ties:Method,down:T), where Method is one
of "average", "minimum" or "ignore" (or simply "a", "m" or "i"), treats
ties as described below.  With REAL x, rank(x,ties:"average" [,down:T])
gives the same ranks as rank(x [,down:T]).  When x is CHARACTER, keyword
'ties' is ignored and is assumed to have value "i".

rank(x [keywords]) has the same labels as x, if any.

@@@@matrix_array_or_structure_argument#Matrix, array, or structure argument
When x is a matrix, the result is a matrix each of whose columns
contains the ranks of the elements of the corresponding column of x.

When x is an array with dimensions n1, n2, ..., the result is an array
of the same size and shape with all the elements with fixed values of
subscripts 2, 3, ... defining a "column" whose ranks are computed.  An
array with dimension > 2 is always treated as an array and not as a
matrix, even if there are at most two dimensions greater than 1.

It is also acceptable for x to be a structure, whose non-structure
components are all REAL or all CHARACTER.  In that case, rank() returns
a structure of the same form, each of whose non-structure components is
the result of applying rank() to the corresponding component of x.

@@@@missing_values#MISSING values
When x is REAL and there are MISSING values in a column, their rank is
also MISSING and the maximum rank of the non-missing values is the
number of non-missing values.

@@@@treatment_of_ties#Treatment of ties
                     Treatment of Ties with REAL Data
Suppose k elements in a vector (column) are tied, that is they all have
the same value and no other element has this value, and suppose the
ranks these elements would have if their values were very slightly
changed so as to break the ties while preserving other ordering would be
r, r+1, r+2, ..., r+k-1.  The following describes the ranks computed for
the tied values for each of the three possible methods.

     Value for 'ties'                    Computed ranks
 "average" or "a" (default)  All ranks = (r+(r+1)+...+(r+k-1))/k =
                             r+(k-1)/2
 "minimum" or "m"            All ranks = r
 "ignore" or "i"             r, r+1, r+2, ..., r+k-1; which ranks go in
                             which position is unpredictable

@@@@examples#Examples
Examples:
  Cmd> x <- vector(27,22,25,26,22,21,?,24) # 1 tie, 1 MISSING

  Cmd> rank(x) # or rank(x,ties:"a")
  WARNING:  MISSING values in argument to rank
  (1)           7         2.5           5           6         2.5
  (6)           1     MISSING           4

  Cmd> rank(x,down:T)
  (1)           1         5.5           3           2         5.5
  (6)           7     MISSING           4

  Cmd> rank(x,ties:"m")
  (1)           7           2           5           6           2
  (6)           1     MISSING           4

  Cmd> rank(x,ties:"m",down:T)
  (1)           1           5           3           2           5
  (6)           7     MISSING           4

  Cmd>  rank(x,ties:"i")
  (1)           7           2           5           6           3
  (6)           1     MISSING           4

In each example except the first, a warning message about MISSING values
has been deleted.

@@@@see_also#Cross references
See also grade(), sort().
@@@@______

====rankits()#transformations,descriptive statistics,ordering
%%%%
rankits(x [,ties:"ignore" or "average" or "minimum"]), x REAL or a
  structure with REAL components.
rankits(n:N), integer N > 0
%%%%
@@@@usage#Usage
rankits(x) computes the vector of rankits (normal scores) for data in
REAL vector x.

rankits(n:N), N a positive integer, is equivalent to rankits(run(N)).

An important use is plot(rankits(x),x) which produces a rankit or normal
scores plot of the values in x.  What is computed is equivalent to
            invnor((rank(x,ties:"ignore") - .375)/(n + .25))
where n is the number of non-MISSING values.  The value corresponding to
a MISSING value is MISSING.

rankits(x [keywords]) has the same labels as x, if any.

@@@@handling_of_ties#Handling of ties
rankits(x,ties:method), where method is "ignore", "average", or
"minimum" (or "i", "a", "m") computes
             invnor((rank(x,ties:method) - .375)/(n + .25))
See rank() for a detailed discussion of the three methods.  It is hard
to think of a situation when you would want to use "minimum" with
rankits().

@@@@matrix_array_or_structure_argument#Matrix array or structure argument
When x is a matrix, the result is a matrix each of whose columns
contains the rankits for the corresponding column of x.

When x is an array, rankits(x) is an array of the same size and shape
with all the elements with fixed values of subscripts 2, 3, ... defining
a "column" whose rankits are computed.  An array with dimension > 2 is
always treated as an array and not as a matrix, even if there are at
most two dimensions greater than 1.

It is also acceptable for x to be a structure, whose non-structure
components are all REAL.  In that case, rankits() returns a structure of
the same form, each of whose non-structure components is the result of
applying rankits() to the corresponding component of x.

@@@@example#Example
  Cmd> x <- vector(10.59,18.82,19.46,13.34,13.49)#ranks are 1,4,5,2,3

  Cmd> rankits(x)
  (1)     -1.1798      0.4972      1.1798     -0.4972           0

@@@@see_also#Cross references
See also halfnorm().
@@@@______

====rational()#transformations
%%%%
rational(x, a, b) or rational(x, a) or rational(x,,b), x REAL or a
  structure with REAL components, a and b REAL vectors
%%%%
@@@@usage#Usage
rational(x,a,b) computes a rational function of the REAL vector, matrix,
or array x, with coefficients for the numerator and denominator
polynomials in REAL vectors a and b.  The result is REAL with the same
size and shape as x.

The rational function computed is
   (a[1] + a[2]*x + a[3]*x^2+ ... )/(b[1] + b[2]*x + b[3]*x^2+ ... ) .

If a or b is omitted, it is construed to represent the constant 1.  For
example, rational(x,a), rational(x,a,), and rational(x,a,1) are
equivalent and compute a polynomial in x, and rational(x,,b), and
rational(x,1,b) are equivalent and compute the reciprocal of a
polynomial in x.

x can also be a structure, all of whose non-structure components are
REAL, in which case the result is a similar structure.

@@@@example#Example
An important use of rational() is in writing macros to compute
mathematical functions that are not directly available in MacAnova but
which can be approximated by rational functions.  For example

  Cmd> cumnor1 <- macro("@x <- $1; @posx <- @x > 0
     @posx - (@posx - .5)*rational(abs(@x),1,\\
       vector(1,.196854,.115194,.000355,.019527))^4", dollar:T)

creates macro cumnor1() which uses an approximation due to Hastings to
cumpute cumulative normal probabilities.  For more elaborate use, see
macros i0() and i1() in file Math.mac distributed with MacAnova.

@@@@see_also#Cross references
See topics macro() and 'macros'.
@@@@______

====rbin()#random numbers
%%%%
rbin(N, n, p), N positive integer, n scalar or vector of positive
  integers, p scalar or vector of probabilities.
%%%%
@@@@usage#Usage
rbin(N, n, p) returns a vector of N independent binomial pseudo-random
variables with sample size n and probability p.  N must be a positive
integer.

n must be a positive integer scalar or a vector of N positive integers.
p must be a REAL scalar between 0 and 1 or a vector of N values between
0 and 1.  If n or p is a scalar, it is used for every element of the
result.  Otherwise, n[i] and/or p[i] are used for the i-th element of
the result.

If the random number generator has not been initialized by setseeds(),
setoptions() or previous use of rbin(), rnorm(), rpoi() or runi(), the
generator's "seeds" will be initialized automatically using the current
time and date, and their values will be printed out.

@@@@use_in_generating_other_distributions#Use in generating other distributions
rbin() can be used to generate other random variables by using a random
vector as p and/or n.  For example,

  Cmd> y <- rbin(N, n, invbeta(runi(N),a, b)) # a, b > 0

will generate a pseudo-random beta-binomial sample variables with
parameters n, a and b.  See the User's Guide for details.

@@@@algorithm#Algorithm
The generation algorithm is adapted from Voratas Kachitvichyanukul and
Bruce Schmeiser, "Binomial random variate generation", Commun.ACM, 31
(1988) 216-222, published as Algorithm 678, Trans. Math. Software 15,
394-397.

@@@@see_also#Cross references
See also topics setseeds(), getseeds(), setoptions(), rnorm(), rpoi(),
runi(), invbeta(), cumbin(), 'options'.
@@@@______

====read()#macros,input,files,missing values
%%%%
x <- read(FileName, setName or macroName [,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.
%%%%
@@@@relationship_to_matread_and_macroread#Relationship to matread() and macroread()
read() can be used instead of either matread() and macroread().  It
recognizes the same keywords.  In fact, the only difference from
matread() and macroread() is that matread() gives a warning message when
reading a macro and macroread() gives a warning message when reading a
data set.  read() makes no such complaint.  See matread() and
macroread() for details.

@@@@see_also#Cross references
See also topics getdata(), getmacros(), vecread(), readcols(),
'matread_file', 'macro_files'.
@@@@______

====readcols()#input,files
%%%%
readcols(FileName,name1,name2,...,namek[,keyword phrases]). FileName a
  quoted string or CHARACTER scalar, name1, ... quoted or unquoted
  variable names.  FileName can also be CONSOLE or have the form
  string:charVal where charVal is CLIPBOARD or other CHARACTER scalar or
  vector.  Keyword phrases may 'realorchar:T' or any vecread() keyword
  phrases except startline:M
readcols(FileName,vector("name1",...,"namek")[,keyword phrases])
readcols(FileName[,keyword phrases]), the first line of the file
  containing names.
%%%%
@@@@usage#Usage
readcols(FileName,name1,name2,...,namek) uses vecread() to read
numerical data from file FileName and puts the columns in variables
name1, name2, ..., namek which be quoted or unquoted.

readcols(FileName,vector("name1",...,"namek")) is an alternative usage.

The file should consist of k columns of numbers separated by spaces,
commas or tabs, with MISSING values indicated by '?' or '.'.  See topics
'vecread_file' and vecread() for a complete description of the file
format, including 'skip', 'skipthru', 'go', and 'stop' characters.

For all usages, the number of variable names must divide the total
number of data values.

@@@@variable_names_from_file#Variable names from file
readcols(FileName), with no variable names provided, does the same,
except that the names are taken from the first non-blank line of the
file, with data assumed to start on the next line.  An informative
message about the variables created is printed.

@@@@forms_for_filename#Forms for filename
FileName can take two forms:
 A quoted string or CHARACTER scalar whose value is the file name.  In
 a version with windows, when FileName is "", you can select the file 
 using a dialog box.  A variant is keyword phrase file:FileName.

 The keyword phrase string:CharVector, where CharVector is a CHARACTER
 scalar or vector which is "read" instead of a file.  When
 length(CharVector) > 1, each element starts a new line.  Any newline
 characters '\n' terminate lines. In windowed versions, string:CLIPBOARD
 can be useful.  See vecread(), 'CLIPBOARD'.

@@@@reading_character_data#Reading CHARACTER data
readcols(FileName,name1,name2,...,namek, bywords:T) and
readcols(FileName, bywords:T) do the same, except that CHARACTER vectors
are created.

readcols(FileName,name1,name2,...,namek, realorchar:T) and
readcols(FileName, realorchar:T) do the same, except both REAL and
CHARACTER vectors may be created.  If the first value in a column is
readable as a number, the corresponding variable will be REAL; otherwise
the variable will be CHARACTER.

@@@@other_keywords#Other keywords
readcols() recognizes the same keyword phrases as vecread(), except
'startline:M' and 'bylines:T'.  These include skip:skipChar,
stop:stopChar, go:goChar, skipthru:skipthruChar, bypass:m, quiet:T or F,
and echo:T or F.  You can't use 'bywords:T', 'bychar:T' or 'byfields:T'
with 'realorchar:T'.  See vecread().

@@@@examples#Examples
Examples:
  Cmd> readcols("hald.txt",x1,x2,x3,x4,y)
  Cmd> readcols(file:"hald.txt",vector("x1","x2","x3","x4","y"))

both create variables, x1, x2, x3, x4 and y from the five columns of
data in hald.txt.

  Cmd> readcols(string:"x y\n 1 2\n 7 9\n ? 4")
  Cmd> readcols(string:vector("x y","1 2","7 9","? 4"))

both of which have the same effect as
  Cmd> x <- vector(1,7,?); y <- vector(2,9,4)

@@@@see_also#Cross references
See also topics readdata(), vecread(), 'macros'.
@@@@______

====readdata()#input,files
%%%%
readdata(filename,name1,...,namek [,factors:F  or sort:F]
  [,keyword phrases]), filename a CHARACTER scalar, name1,... names,
  quoted or unquoted variable names
readdata(filename,vector("name1",...,"namek") [,factors:F or sort:F]
  [,keyword phrases])
readdata(filename [,factors:F or sort:F] [,keyword phrases])
%%%%
@@@@usage#Usage
readdata(FileName,name1,name2,...,namek) uses vecread() to read
one or more columns of data from file FileName, creating variables.
name1, name2, ..., namek.  The variable names can be either quoted
("weight") or unquoted (weight) but must be legal MacAnova names.

When the value of a variable in the first line of the data is not a
number, the values for that variable are read as CHARACTER data and then
turned into a factor, with factor levels maintaining the alphabetical
order of the CHARACTER values.

readdata(FileName,name1,...,sort:F) does the same except if any factors
are created, the factor levels are assigned in the order CHARACTER
values are encountered.

readdata(FileName,name1,...,factors:F) does the same except a column
starting with a non-numerical word is not translated into a factor but
is read as a CHARACTER vector.

readdata(FileName [,factors:F or sort:F]) does the same except the names
for the variables are expected to be in the first line of the file.

For all usages, the number of variable names, whether given as arguments
or taken from the first line of the file, must divide the total number
of data values.

@@@@printed_output#Printed output
A line giving the name and type (REAL, factor or CHARACTER) is printed
for each variable read.  If the variable is REAL and has MISSING values,
the number of MISSING values is also printed.  Argument 'quiet:T'
suppresses this output.

Any line in the file starting with skip character '#' is automatically
skipped and is echoed to output by default.

@@@@relation_to_readcols#Relation to readcols()
readdata() is intended as a replacement for readcols().  It can handle
files in which some data columns are non-numerical and can get variable
names from the first line of the file.

@@@@file_format#File format
The file should consist of k columns of "words" separated by spaces,
commas or tabs.  A word is any set of consecutive characters not
including a comma, space or tab.

A column whose first word is a number or MISSING ('?', '.', '*' or 'NA')
is read as a REAL vector.  Any word in the column after the first which
is not readable as a number (for example 5a3) is read as MISSING.

When the first word in a column is not a number or a code for MISSING,
the corresponding variable is a factor, by default, with a level for
each distinct word in the column.  The factor has the original words in
the file as row labels.  With 'factor:F' as an argument, the column is
read as a CHARACTER variable instead of a factor.

@@@@forms_for_filename#Forms for filename
FileName can take two forms:
 A quoted string or CHARACTER scalar whose value is the file name.  In
 a version with windows, when FileName is "", you can select the file 
 using a dialog box.  A variant is keyword phrase file:FileName.

 The keyword phrase string:CharVector, where CharVector is a CHARACTER
 scalar or vector which is "read" instead of a file.  When
 length(CharVector) > 1, each element starts a new line.  Any newline
 characters '\n' terminate lines. In windowed versions, string:CLIPBOARD
 can be useful.  See vecread(), 'CLIPBOARD'.

@@@@vecread_keywords#vecread() keywords
You can use most vecread() keywords 'quiet', 'silent', 'stop', 'skip',
'skipthru', 'go', 'quiet', 'echo', and 'n', but not 'bypass', 'bywords',
'bylines', 'bychars', 'byfields' and 'realorchar'.  See topic
'vecread_keys'.

@@@@see_also#Cross references
See also readcols(), vecread(), 'vecread_files'.
@@@@______

====redo()#control
%%%%
redo() or redo(charVar) where charVar is CHARACTER scalar
REDO()
%%%%
@@@@usage#Usage
redo() re-executes the previous line.  It can be used in an expression
3*redo() or as an argument to a function (sqrt(redo())).

What redo() actually does is the following:
 1. redo() creates a macro REDO from the entire preceding command line
    which is automatically saved as variable LASTLINE
 2. redo() then executes REDO, thus re-running the preceding command
    line.  Re-execution may not be exact.  If the preceding line
    consisted of several commands separated by semi-colons, they will
    all be executed, but values that are not assigned will not be
    printed, except for the final command.  And even if the final
    command in the preceding line is an assignment, its value may be
    printed.

In later lines, just typing REDO() will re-execute this line (until a
subsequent use of redo()).

Caution: do not attempt to use redo() immediately following a line
containing redo() or REDO(), as this leads to uncontrolled recursion.

redo(charVar) also creates macro REDO and executes it, but the contents
of REDO come from CHARACTER scalar charVAR rather than LASTLINE.

redo() is implemented as a pre-defined macro.

@@@@examples#Examples
Examples:
  Cmd> print(paste("Pi =",PI))
  Pi = 3.1416

  Cmd> redo() # previous command repeated
  Pi = 3.1416

  Cmd> REDO() # redone command repeated
  Pi = 3.1416

  Cmd> pi <- PI # line ending in assignment

  Cmd> redo() # previous line executed and value of assignment printed
  (1)      3.1416

  Cmd> pi <- PI ;; # note trailing ;; so last command is null

  Cmd> redo()  # previous line executed and nothing printed

  Cmd>

@@@@see_also#Cross references
See also topics edit(), 'macros', 'syntax'.
@@@@______

====regcoefs()#glm,anova,regression,confidence intervals
%%%%
regcoefs(Model [,pvals:T] [,byvar:F]) or regcoefs([pvals:T] [,byvar:F]),
  where Model is a CHARACTER scalar
%%%%
@@@@usage#Usage
regcoefs(Model) returns a matrix with appropriately labeled rows and
columns of the regression coefficients, their standard errors and
t-statistics from a least squares fit to the regression model specified
by Model.  There can be no factors in Model.  If Model is omitted, the
most recent GLM model is used.

regcoefs(Model,pvals:T) or regcoefs(pvals:T) also computes two-tail P
values corresponding to the t-statistics on the basis of Student's
t-distribution with degrees of freedom from the last element of side
effect variable DF.

Because of the presence of row and column labels, after any GLM command
with a model without factors, typing regcoefs([pvals:T]) produces a
table similar to that produced by regress().  After non-linear fits such
as logistic() or poisson(), the P-values will not necessarily be
appropriate.

@@@@multivarate_response#Multivarate response
If the response variable is multivariate, the result is a structure,
each of whose components is a labeled matrix of coefficients, standard
errors and t-statistics.  regcoefs(Model,byvar:F) or regcoefs(byvar:F)
returns a single labeled matrix, with separate columns for the
coefficients, standard errors, ... for each variable.

@@@@see_also#Cross references
See also topics 'glm', regress(), secoefs().
@@@@______

====regpred()#glm,regression
%%%%
regpred(vals [, silent:T]), vals a REAL vector or matrix.
%%%%
@@@@usage#Usage
regpred(vals) computes the fitted (predicted) value, the standard error
of estimation, and the standard error of prediction for the current
regression model when the X variables have values given by the REAL
vector or matrix vals.

When there is only 1 variate in the model, vals is a scalar or a vector
and the estimates and standard errors are computed for each element of
vals.

When the number of variates in the model is nvars > 1, vals must either
be a vector of length nvars containing data for a single case, or a m by
nvars matrix containing data for m cases.  In the latter case, each
component of the result is a vector of length m.  For example, after
regress("y=x1+x2+x3"), regpred(hconcat(x1,x2,x3)) computes the predicted
values and standard errors for all cases in the data set.

The result is a structure with components 'estimate', 'SEest', and
'SEpred'.

When the error degrees of freedom are 0, all standard errors are set to
MISSING.

Caution: After anova(), manova() and regress(), standard errors are
computed using the final error mean square in the model.  This may not
be appropriate with mixed models, including split plot designs.

@@@@keywords#Keywords
regpred(vals, silent:T) does the same except certain advisory messages
are suppressed.  The default value of 'silent' is False unless the value
of option' 'warnings' is False.

You can also use keyword phrases estimate:F, seest:F, sepred:F and n:N.
See glmpred() for details.

@@@@when_used#When used
You can use regpred() after any GLM command as long as there are no
factors in the model.  The output has no SEpred component except after
regress(), anova() or manova() or their weighted versions.

After anova(), manova() and regress(), regpred(vals) is equivalent to
glmpred(vals,sepred:T).  After other GLM commands, regpred(vals) is
equivalent to glmpred(vals).

@@@@see_also#Cross references
See also topics regress(), anova(), glmpred(), predtable(), glmtable(),
modelinfo(), popmodel(), pushmodel(), 'glm', yhat().
@@@@______

====regress()#glm,regression
%%%%
regress([Model] [,print:F or silent:T,pvals:T,coefs:F,marginal:T])
%%%%
@@@@usage#Usage
regress(Model) performs a least squares fit of the regression model
given in the quoted string or CHARACTER variable Model.  It prints out
the regression coefficients, their standard errors, and t statistics,
plus other summary statistics (see below).  If option 'pvals' is True,
regress() also prints P values for each coefficient based on Student's t
distribution.  See subtopic 'options:"pvals"'.

No ANOVA table is printed by regress().  To see one, type 'anova()' as
the next GLM command after regress().

@@@@examples#Examples
Examples (y, x, x1, x2, and x3 all REAL vectors of length 10):
   regress("y = x")                 Simple linear regression of y on x
   regress("y = x - 1")             Linear regression through origin of
                                    y on x
   regress("y = {run(10)}")         Simple linear regression of y on
                                    vector(1,2,3,4,5,6,7,8,9,10)
   regress("y = x1 + x2 + x3")      3 variable multiple regression of y
                                    on x1, x2 and x3
   regress("{sqrt(y)} = x + {x^2}") Quadratic polynomial regression of
                                    sqrt(y) on x
   regress("{sqrt(y)} = P2(x)")     Same as preceding.

@@@@weights_keyword#Keyword 'weights'
regress(Model,weights:Wts) performs a weighted least squares fit, using
REAL vector Wts as case weights. The elements of Wts must not be
negative.  The results are what you would get by multiplying by
sqrt(Wts) the response vector and all independent variables, including
the contant vector, and then doing a least squares fit.  You can
abbreviate 'weights:Wts' to 'wts:Wts'.

@@@@model_for_regress#Model for regress()
Model is of the form "Response = Var1 + Var2 + ... + Vark", where
Response, Var1, ..., Vark are either variable names or have the form
{expr}, where expr is a MacAnova expression.  All variables or evaluated
expressions must be REAL with the same number of rows.  The variables to
the right of '=' must be vectors or n by 1 matrices.  If any right hand
side variable is actually a factor, it is treated as a quantitative
variate whose values are the levels of the factor.  The associated sum
of squares has only 1 degree of freedom regardless of the number of
levels of the factor.

@@@@regression_through_origin#Regression through origin
You specify regression through the origin by including "-1" in the
model.  See also topic 'models'.

@@@@no_model_specified#No model specified
regress() or regress(,weights:Wts) with no model specified computes a
least squares regression using the same model as was used by the most
recent GLM command such as regress(), anova(), or poisson().  See topic
'glm'.

@@@@printed_output#Printed output
Other printed output from regress() includes multiple R-squared, the
overall F-statistic for the model excluding the constant term, the mean
squared error and the Durbin Watson statistic.

@@@@side_effect_variables_created#Side effect variables created
regress() computes side effect variables RESIDUALS, HII, SS, DF,
DEPVNAME, TERMNAMES, STRMODEL, COEF, and XTXINV.  When weights are used,
RESIDUALS = response - fit and WTDRESIDUALS = sqrt(Wts)*RESIDUALS is an
additional side effect variable.  When an independent variable is of the
form {expr}, the corresponding element of TERMNAMES is "{expr}".  See
topic 'glm'.

@@@@use_of_coefs_or_secoefs#Use of coefs() or secoefs()
You can retrieve coefficients and/or their standard errors using coefs()
or secoefs().

@@@@keywords
                          Other Keywords
Keyword phrase  Default  Meaning
  print:F          T     Suppress all output except warning and error
                         messages.  Side effect variables are set.

  silent:T         F     Suppress all output except error messages.
                         Side effect variables are set.

  pvals:T          F     Print P values.  Default is T when option pvals
                         is T (see subtopic 'options:"pvals"')

  marginal:T       F     Specifies that the elements of the side effect
                         variable SS are computed marginally. When none
                         of the X-variables are aliased, the computed SS
                         are equivalent to SAS Type III SS.  See topic
                         'glm' for details.  SS will be printed by
                         anova() with no intervening GLM command.

Keyword phrase 'coefs:F' is not legal with regress().

@@@@see_also#Cross references
See also anova().
@@@@______

====regresshelp()#general,regression,confidence intervals,glm
%%%%
regresshelp(topic1 [, topic2 ...] [,usage:T] [,scrollback:T])
regresshelp(topic, subtopic:Subtopics), CHARACTER scalar or vector
  Subtopics
regresshelp(topic1:Subtopics1 [,topic2:Subtopics2 ...])
regresshelp(key:Key), CHARACTER scalar Key
regresshelp(index:T [,scrollback:T])
%%%%
@@@@usage#Usage
regresshelp(Topic1 [, Topic2, ...]) prints help on topics Topic1,
Topic2, ... related to macros in file regress.mac.  The help is taken
from file regress.mac.

regresshelp(Topic1 [, Topic2, ...] , usage:T) prints usage information
related to these macros.

regresshelp(index:T) or simply regresshelp() prints an index of the
topics available using regresshelp().  Alternatively,
help(index:"regress") does the same thing.

regresshelp(Topic, subtopic:Subtopic), where Subtopic is a CHARACTER
scalar or vector, prints subtopics of topic Topic.  With subtopic:"?", a
list of subtopics is printed.

regresshelp(Topic1:Subtopics1 [,Topic2:Subtopics2], ...), where
Suptopics1 and Subtopics2 are CHARACTER scalars or vectors, prints the
specified subtopics.  You can't use any other keywords with this usage.

In all the first 4 of these usages, you can also include help() keyword
phrase 'scrollback:T' as an argument to regresshelp().  In windowed
versions, this directs the output/command window will be automatically
scrolled back to the start of the help output.

@@@@key_keywords#Keyword 'key'
regresshelp(key:key) where key is a quoted string or CHARACTER scalar
lists all topics cross referenced under Key.  regresshelp(key:"?")
prints a list of available cross reference keys for topics in the file.

@@@@______
regresshelp() is implemented as a predefined macro.

@@@@see_also#Cross references
See help() for information on direct use of help() to retrieve
information from regress.mac.
@@@@______

====releigen()#matrix algebra
%%%%
releigen(h,e [,maxit:N, nonconvok:T]), h and e symmetric REAL matrices
  with no MISSING values, e positive definite, integer N > 0
%%%%
@@@@usage#Usage
releigen(H,E) computes an eigenvector/eigenvalue decomposition of the
symmetric matrix H relative to the symmetric positive definite matrix E.
Arguments H and E must both be p by p symmetric matrices with no MISSING
values.

The value returned is structure(values:Vals,vectors:Vecs), where Vals is
the length p vector of relative eigenvalues in decreasing order and Vecs
is a p by p matrix whose columns are the relative eigenvectors.

If H and E are MANOVA hypothesis and error matrices, respectively, you
can use the relative eigenvalues to compute several standard
multivariate hypothesis tests, and the elements of the relative
eigenvectors are the coefficients of the MANOVA canonical variables
associated with the hypothesis.

@@@@properties_of_result#Properties of result
After
  Cmd> releigs <- releigen(H,E) # H and E p by p

  Cmd> v <- releigs$values; u <- releigs$vectors

u is a p by p matrix and v is a vector of length p with elements v[1] >=
v[2] >= ... >= v[p], such that
     H %*% u        = E %*% u %*% dmat(v)
     u' %*% H %*% u = dmat(v)
     u' %*% E %*% u = Ip = p by p identity matrix

On the vector level, this means
     H %*% u[,j] = v[j] * E %*% u[,j], j = 1,...,p
     u[,j]' %*% H %*% u[,j] = v[j], j = 1,..,p
     u[,j]' %*% H %*% u[,k] = 0, j != k
     u[,j]' %*% E %*% u[,j] = 1, j = 1,..,p
     u[,j]' %*% E %*% u[,k] = 0, j != k

dmat(v) is the diagonal matrix with elements of v down the diagonal.

@@@@maxit_and_nonconvok_keywords#Keywords 'maxit' and 'nonconvok'
See eigen() for information on keyword phrases 'maxit:N' and
'nonconvok:T'.

@@@@see_also#Cross references
See also det(), eigen(), eigenvals(), trideigen() and releigenvals().
@@@@______

====releigenvals()#matrix algebra
%%%%
releigenvals(h,e [,maxit:N, nonconvok:T]), h and e symmetric REAL
  matrices with no MISSING values, e positive definite, integer N > 0
%%%%
@@@@usage#Usage
releigenvals(H,E) computes the eigenvalues of the p by p symmetric
matrix h relative to the symmetric positive definite matrix E of the
same size.

The value returned is vector(v1,v2,...,vp), where vj are the relative
eigenvalues with v1 >= v2 >= ... >= vp.  See releigen() for a summary of
the properties of relative eigenvlues.

@@@@maxit_and_nonconvok_keywords#Keywords 'maxit' and 'nonconvok'
See eigen() for information on keyword phrases 'maxit:N' and
'nonconvok:T'.

@@@@see_also#Cross references
See also det(), eigen(), eigenvals() and trideigen().
@@@@______

====rename()#general,variables
%%%%
rename(var, newName), where newName is an undefined variable
%%%%
@@@@usage#Usage
rename(Var, Name) where Name is an undefined variable (no value has been
assigned to it) changes the name of Var to Name. Var may be an existing
variable, a constant such as 3.5, "hello", or T, or an expression such
as 'sqrt(20)' or '3*cos(x) + 4*sin(x)'.  When Var a constant or
expression, rename(Var, Name) is equivalent to Name <- Var.  Unless Name
is a CHARACTER scalar (see below), it must not be a function or an
existing variable or macro.  It is an error if variable Name exists,
unless it is the same variable as Var as in rename(x,x).

rename(Var, nameVar) where nameVar is a quoted string or scalar
CHARACTER variable is equivalent to rename(Var, <<nameVar>>), that is
the new name is the value of nameVar.  For example, rename(x, y) and
rename(x, "y") are equivalent.  The value of nameVar must not be the
name of any existing variable, macro or function and must be a legal
name (see 'syntax').  "NULL", "T", and "F" are not legal names.

It is an error if Var is a locked variable; see lockvars(),
unlockvars(), islock() and variables:"locked_variables".

Var must not be a function or a "special" variable such as CLIPBOARD,
SELECTION or GRAPHWINDOWS.  See topics 'CLIPBOARD', 'GRAPHWINDOWS' and
'graph_assign'.

@@@@alternative#Alternative
You can achieve the same effect as rename(Var,Name) by
  Cmd> Name <- Var; delete(Var)

However, if Var is not a constant or expression, doing it this way
entails the temporary existence in memory of two copies of Var.  If Var
is large, there may not be enough room in your workspace.  The use of
rename() avoids this problem.  For this reason, in a macro that uses
another macro to compute a value, it may sometimes be helpful to use
rename() instead of assignment.

@@@@examples#Examples
Examples:
  Cmd> rename(PI, pi) # or rename(PI,"pi"), change name of PI to pi

  Cmd> e <- 10; rename(E, e) # is an error since e exists

  Cmd> rename(sqrt(2),sqrt2) # same as sqrt2 <- sqrt(2)

The last example would be an error if sqrt2 is already a variable.

@@@@see_also#Cross references
See also nameof(), compnames(), varnames()
@@@@______

====rep()#combining variables,variables
%%%%
rep(x, n) or rep(x, repFac), where x is REAL, LOGICAL, or CHARACTER, and
  n is an integer > 0 or repFac is a vector of integers >= 0
%%%%
@@@@usage#Usage
rep(X, n), where n is a positive integer, replicates the values in X n
times to form a vector of length n*length(X).  It is equivalent to
vector(X,X,X,...,X), where there are n repetitions of X.  X must be a
REAL, LOGICAL or CHARACTER vector, matrix, or array.

rep(X, 0) is legal an has value NULL.

rep(X, Repfac), where Repfac is a vector of integers with length(Repfac)
= length(X) and Repfac[i] >= 0, replicates the j-th element of vector(X)
Repfac[j] times.  The result has length length(X)*sum(Repfac).  If every
element of Repfac is 0, the result is NULL.

@@@@examples#Examples
Examples:
  Cmd> rep(vector(1,3,5),4)  # same as vector(1,3,5,1,3,5,1,3,5,1,3,5)
   (1)           1           3           5           1           3
   (6)           5           1           3           5           1
  (11)           3           5

  Cmd> rep(vector(7,6,5),vector(3,0,2)) # same as vector(7,7,7,5,5)
  (1)           7           7           7           5           5

  Cmd> a <- factor(rep(run(5),4)); b <- factor(rep(run(4),rep(5,4)))

  Cmd> print(a,b) # factors for 4 by 5 factorial design with no reps
  a:
   (1)           1           2           3           4           5
   (6)           1           2           3           4           5
  (11)           1           2           3           4           5
  (16)           1           2           3           4           5
  b:
   (1)           1           1           1           1           1
   (6)           2           2           2           2           2
  (11)           3           3           3           3           3
  (16)           4           4           4           4           4

  Cmd> rep(run(5), vector(1,2,3))# ERROR! (args have different lengths)
  ERROR: in rep(x,m), m must be scalar or a vector the same length as x

@@@@caveat#Warning
WARNING: Because rep() is a function you cannot use the name 'rep' as a
variable name, say for a replication factor in a design.  Use 'Rep' or
'reps' instead.

@@@@see_also#Cross references
See also topics vector(), run(), 'models', 'glm'.
@@@@______

====replacestr()#CHARACTER variables
%%%%
replacestr(source,old,new) replace first instance of old by new
  in source, where all three are Character scalars
%%%%
replacestr(source,old,new) works on three CHARACTER scalar
variables.  It replaces in source the first instance of the string
in old by the string in new.  If old does not appear in source,
then source itself is returned.

====restore()#files,general
%%%%
restore(FileName [ ,delete:F, list:T, history:F, options:F,\
  foreignok:T])
%%%%
@@@@usage#Usage
restore(FileName) restores the workspace or variables previously put in
file FileName by save() or asciisave(), where FileName is a quoted
string or CHARACTER variable.  Unless option 'restoredel' has been set
to False (see subtopic 'options:"restoredel"'), all current variables
are deleted before restoration.  If a history of commands was saved by
using history:T on save() or asciisave(), it replaces the corrent
history of recent commands.

In a version with windows, if FileName is "" you will be prompted for 
the name of the file.  Restore Workspace on the File menu in versions
with windows is equivalent to 'restore("")'.

Restoring a workspace may destroy any existing locked variables.  See
topic 'variables:"locked_variables"'.

@@@@variables_not_restored#Variables not restored
Although variables HOME, DATAFILE, DATAPATHS, MACROFILES, HELPFILES and
HELPINDICES are saved by save() and asciisave(), they are not restored
unless they do not currently exist.

These variables are used to find files containing macros, data and help
information.  See topics adddatapath(), addmacrofile(), getdata(),
getmacros(), 'macros' and 'DATAPATHS'.

Any of these variables that are not restored become components of
structure SAVEDNAMES with components HOME, DATAFILE, DATAPATHS, ....

If you want to restore DATAPATHS, say, you must follow restore() by

  Cmd> DATAPATHS <- SAVEDNAMES$DATAPATHS

or you can use macro restorenames():

  Cmd> restorenames(DATAPATHS)

To restore all these variables after restore(), use

  Cmd> restorenames()

In addition, variable VERSION is not restored and is not saved in
SAVEDNAMES.  Whether or not VERSION exists before restore() is run,
restore() sets it to a value appropriate to the MacAnova version being
run.

These steps help ensure that the values of these variables pertains to
the computer and version you are actually using rather than to
the computer and version used to create the workspace file.  See topics
'files', 'launching'.

@@@@delete_keyword#Keyword 'delete'
restore(FileName, delete:F) does not delete existing variables before
restoring.  However, a variable or macro with the same name as a
variable or macro in the file is replaced by the one in the file.  If
option 'restoredel' has been set to False, it may be overridden by
delete:T.

@@@@history_keyword#Keyword 'history'
restore(FileName, history:F) suppresses restoring of any history of
recent commands that may have been saved.  Use this if you want to
preserve the history of commands immediately preceding the restore()
command.  This is not available in versions that do not save such a
history.  See sethistory() and gethistory().  Note: a command history is
not saved on a save of selected variables.

@@@@options_keyword#Keyword 'options'
restore(FileName, options:F) suppresses restoring the values of options
in effect when the workspace file was created.  Use this if you want to
preserve options currently in effect.  See topics 'options',
setoptions() and getoptions().

Note: option values are not saved on a save of selected variables.

@@@@list_keyword#Keyword 'list'
restore(FileName [,delete:F], list:T) lists information on variables as
they are restored.

@@@@restoring_foreign_binary_files#Restoring foreign binary files
It is normally an error when the file is a binary workspace file from an
incompatible computer, for example, restoring a Macintosh save file on
Windows.

restore(FileName, foreignok:T ...) makes it permissible to try to
restore a binary workspace file from an incompatible computer.  When
necessary and possible, bytes in the internal representation of numbers
are permuted so as to give them correct values.  This is impossible if
either the number of bytes in either a double precision number or a long
integer differ between the machines.

If you are planning to use a save workspace on a different type of
computer, it is safer to save it using asciisave().

@@@@restoring_GRAPHWINDOWS_and_options#Restoring GRAPHWINDOWS and options
Unless 'graphwind:F' was used when the workspace file was created,
special structure GRAPHWINDOWS is restored.  In windowed versions the
windows corresponding to its components are redrawn (see topic
'GRAPHWINDOWS').  If the number of components saved is greater than the
number allowed in the version you are using, extra components are
ignored.  If the number is fewer, missing components are assumed to be
NULL.

Unless options:F is an argument to restore() or was an argument to
save() or asciisave() when the workspace file was created, values for
options such as 'nsig', 'format', and 'seeds' will be restored to the
previous values at the time the save was done (see 'options').

There are a couple of exceptions.
  'prompt' is not restored when input is from a 'batch' file; see
  batch()
  'matchdelay' is not restored when restoring a workspace saved on an
  incompatible system.

@@@@restoring_private_GLM_information#Restoring private GLM information
If all:T was used when the file was created, then private information
related to the most recent GLM command will be restored.  Without this
information certain commands such as secoefs() do not work until a GLM
command has been executed.  See topic 'glm'.

@@@@restoring_old_workspace_files#Restoring old workspace files
Workspace files created by earlier versions of MacAnova for the same
computer can normally be restored correctly except that binary files
created by MacAnova2.4x on a Macintosh cannot be restored.

@@@@see_also#Cross references
See also topics asciisave(), save(), restorenames(), 'options', 'files'.
@@@@______

====restorenames()#files,general,structures
%%%%
restorenames()
restorenames(name1 [,name2, ...]), name1, name2, ... are any of these
  variable names: HOME, DATAFILE, DATAPATHS, MACROFILES, HELPFILES,
  HELPINDICES
%%%%
@@@@usage#Usage
restore() does not overwrite certain variables containing information on
the location of data, macro and help files.  These variables are HOME,
DATAFILE, DATAPATHS, MACROFILES, HELPFILES and HELPINDICES.  Instead,
it creates a structure SAVEDNAMES containing the values of these
variables in the workspace file being restored.  restorenames() is
provided to make it easy to overwrite any or all of these variables
after restore().

restorenames() restores all the variables in SAVEDNAMES.

restorenames(name1 [, name2, ...]) restores just the named variables.
name1, name2, ... must be names of components of SAVEDNAMES, normally
HOME, DATAFILE, DATAPATHS, MACROFILES, HELPFILES and HELPINDICES.

@@@@examples#Examples
Example:
  Cmd> restore("workspace.030320")

  Cmd> restorenames(MACROFILES, HELPFILES)

@@@@see_also#Cross references
See also restore(), save(), getdata(), getmacros(), addmacrofile(),
adddatapath(), addhelpfile(), 'workspace'.

====return#control,syntax,macros
%%%%
return(x), x a variable or constant, only in a macro
return and return() are equivalent to return(NULL)
%%%%
@@@@description_and_usage#Description and usage
Syntax element 'return' is used to leave a macro immediately, skipping
any following expressions or commands.  It may be used only in the text
of a macro.

In a macro, when 'return(Value)' is executed, the macro is immediately
terminated and Value is returned as the macro value.  Value can be any
constant, variable or expression.  'return(Value)' must be followed by
';' or '}' or be at the end of a line.

In a macro, 'return()' and 'return', with no parentheses, are equivalent
to 'return(NULL)'.

@@@@where_return_is_used#Where 'return' is used
'return(Value), 'return()' and 'return' are typically the last command
in the compound command (see topic 'syntax') that follows 'if(...)',
'elseif(...)' or 'else' (see topic 'if'), or as the last command in a
macro.

'return' may not be used in an evaluated string unless it is in a macro
invoked in that evaluated string.  This is true even if the string being
evaluated is within a macro.  See evaluate().

@@@@example#Example
Example:
  Cmd> checkit <- macro("if($1==1){return(\"one\")}
       if($1 == 2){return(\"two\")};return(\"not one or two\")")

  Cmd> reply <- checkit(1); reply
  (1) "one"

  Cmd> reply <- checkit(3); reply
  (1) "not one or two"

The final 'return(...)' could be replaced simply by "not one or two",
since the default return value is the last expression or variable in the
macro.

@@@@see_also#Cross references
See also macro(), 'macros', 'macro_syntax', 'break', 'next'
@@@@______

====reverse()#time series
%%%%
reverse(x), x a vector or matrix.
%%%%
@@@@usage_and_examples#Usage and examples
reverse(x) reverses the order of the rows of x, where x is a REAL,
LOGICAL or CHARACTER vector or matrix.

The result has the same size and type as x.  When isvector(x) is True,
the result is a pure vector (ndims(x) = 1).  Otherwise, the result has 2
dimensions.

Examples:
  Cmd> reverse(vector(1,3,2,4,7))
  (1)           7           4           2           3           1

  Cmd> reverse(matrix(run(6),3))
  (1,1)           3           6
  (2,1)           2           5
  (3,1)           1           4

  Cmd> reverse(matrix(vector("A","B","C","D")))
  (1) "D"
  (2) "C"
  (3) "B"
  (4) "A"

@@@@______

====rft()#time series,complex arithmetic
%%%%
rft(rx [,divbyT:T]), rx a REAL matrix
%%%%
@@@@usage#Usage
rft(rx) where rx is a REAL vector or matrix, computes the Hermitian form
of the complex discrete Fourier transform of each column of rx,
considered as a real series.

Any MISSING values in rx are replaced by 0 in computing the result and a
warning message is printed.

rft(rx,divbyt:T) does the same except the result is divided by the
number of rows of rx.

@@@@inverse_transform#Inverse transform
hft(hconj(hx),divbyt:T) is the inverse of rft() in the sense that rx and
hft(hconj(rft(rx)),divbyt:T) are equal except for rounding error.

@@@@limitation_on_length#Limitation on length
The largest prime factor of nrows(rx) must not exceed 29.  You can use
primefactors() to find the maximum factor of nrows(rx) and goodfactors()
to find a length >= nrows(rx) which has no prime factors > 29.  In
addition, the product of all the "unpaired" prime factors can't be too
large.  For example N = 3*5*7*11*13*17*M^2 = 255255*M^2, where M is an
integer, breaks the algorithm and hence is not allowed.

@@@@see_also#Cross references
See also cft(), hft(), hconj(), primefactors(), goodfactors().

See topic 'complex' for discussion of complex matrices in MacAnova.

See subtopic 'matrices:"complex_matrices" for a list of macros for
working with complex matrices.
@@@@______

====rnorm()#random numbers
%%%%
rnorm(n), n a positive integer
%%%%
@@@@usage#Usage
rnorm(N) generates a vector of N pseudo-random normals with mean 0 and
variance 1.  N must be a positive integer.

If the random number generator has not been initialized by setseeds(),
setoptions() or previous use of rbin(), rnorm(), rpoi() or runi(), the
generator's "seeds" will be initialized automatically using the current
time and date, and their values will be printed out.

To generate a pseudo random sample from the normal distribution with
mean mu and standard deviation sigma do the following.
  Cmd> y <- mu + sigma*rnorm(N) # sigma > 0 and mu REAL scalars

@@@@see_also#Cross references
See also topics setseeds(), getseeds(), setoptions(), rbin(), rpoi(),
runi(), cumnor() and invnor(), subtopic 'options:"seeds"'.
@@@@______

====robust()#glm,anova,regression
%%%%
robust([Model] [,print:F or silent:T, trunc:c, maxiter:m, epsilon:eps, \
  fstats:T, pvals:T, marginal:T]), Model a CHARACTER scalar,
  c and eps positive REAL scalars, m a positive integer.
%%%%
@@@@usage#Usage
robust(Model) computes a robust linear fit of the model specified in the
quoted string or CHARACTER variable Model.  An approximate analysis of
variance (ANOVA) table is printed, as well as a robust estimate of
sigma.  In the case of normal errors with possible outliers arising from
contamination, the square of the estimated sigma is approximately
unbiased for the variance of the uncontaminated errors.

See topic 'models' for information on specifying Model.

When Model is omitted (robust() or robust(,...), the most recent GLM
model is assumed, or, if there have not been previous GLM commands, the
model specified in variable STRMODEL, if any.

@@@@side_effect_variables_created#Side effect variables created
Side effect variables created by robust() are DF, SS, HII, RESIDUALS,
and WTDRESIDUALS.  WTDRESIDUALS is not really weighted residuals;
instead it is set to the vector of modified residuals
sigmahat*psi(residuals/sigmahat).  See below for details.

Inference based on the ANOVA table should be used with caution.
Especially when there are cases with high leverage (large value of HII),
or when the ratio of model degrees of freedom to error degrees of
freedom is too large, the approximation can be misleading.  Interpret
with similar caution the results of secoefs() and contrast() after
robust().

@@@@trunc_maxiter_and_epsilon_keywords#Keyword 'trunc', 'maxiter' and 'epsilon'
Keyword phrase  Default  Meaning
  trunc:c         .75    Positive REAL c is used as a "truncation point"
                         in the fitting algorithm.  See discussion
                         below.  The larger the value, the less
                         "robustifying."

  maxiter:m       50     Positive integer m is the maximum number of
                         iterations that will be allowed in fitting

  epsilon:eps    1e-6    Small positive REAL specifying relative error
                         in objective function required to end iteration

@@@@other_keywords#Other keywords
See topic 'glm_keys' for information on keyword phrases 'print:F',
'silent:T', 'fstats:T', 'pvals:T' and 'marginal:T'.  Any P values
printed by fstats:T and pvals:T are only approximate.  Keyword phrase
'coefs:F' is not legal.

The default values for fstats and pvals can be changed by
setoptions(fstats:T) and/or setoptions(pvals:T).  See setoptions(),
options.

@@@@algorithm_used#Algorithm used
The algorithm used is based on Sec. 7.8 of "Robust Statistics" (Wiley
1981) and Sec. 14 of "Robust Statistical Procedures" (SIAM 1977), both
by Peter J. Huber.  Coefficients and scale sigma are estimated by
minimizing a certain function of sigma and the residuals r = y - fit
(Huber 1981, eq. 7.7.9 and 7.7.14).

Effectively the algorithm deemphasizes cases whose apparent residual
r[i] satisfies abs(r[i]) > c * sigma, where c is a constant "truncation
point".  The default value of c is .75 but it can be set by keyword
'trunc'.

@@@@contents_of_WTDRESIDUALS#Contents of WTDRESIDUALS
After running robust(), WTDRESIDUALS contains the modified residuals
rmod = sigmahat*psi(rhat/sigmahat), where sigmahat is the estimated
scale, rhat is the vector of estimated residuals, and psi(z) = z when
abs(z) < c, psi(z) = c for z >=c, psi(z) = -c, z <= -c.

@@@@contents_of_ANOVA_table#Contents of ANOVA table
Following a suggestion of Huber, the ANOVA table is computed from
pseudo-data obtained as fithat + K*rmod, where fithat = y - rhat is the
vector of estimated predicted values and K is a constant (see p. 40 of
Huber 1977).  K = (1 + (k/n)(1-mu)/mu)/mu, where n is the sample size, k
is the number of model degrees of freedom, and mu = m/n where m is the
number of non-truncated rhat[i], that is, which satisfy
abs(rhat[i]/sigmathat) < c.  The robust estimate of sigma is
sqrt(mse/beta)/K, where mse is the error mean square from the ANOVA
table and beta is a constant computable by beta = cumchi(c^2,3) +
2*c^2*(1 - cumnor(c)) = E[psi(z^2)] for N(0,1) z.

If you want ANOVA results with a different order of terms, you do not
need to redo robust(); you can use anova() with the pseudo-data in the
preceding paragraph as dependent variable.  You can determine m needed
to compute K as the number of cases for which WTDRESIDUALS and RESIDUALS
are equal except for rounding error.
@@@@______

====rotate()#time series,combining variables
%%%%
rotate(x, k), x a vector or matrix, k an integer.
%%%%
@@@@usage#Usage
rotate(x, k) "rotates" by k rows each column of the REAL, LOGICAL or
CHARACTER vector or matrix x.  When k > 0, rows pushed down off the end
are shifted to the start and when k < 0, rows pushed up before the start
are moved to the end.  k must be a single integer and is interpreted
modulo nrows(x).  For example, rotate(x,k) and rotate(x,k %% nrows(x))
are equivalent.

More explicitly, for -m < k < m, where m = nrows(x), rotate() moves rows
as follows:
  0 <= k <= m-1 (down column shift)   -(m-1) <= k <= 0 (up column shift)
 Row j -> Row j+k   for j=1,...,m-k   Row j -> Row j+k+m for j=1,...,-k
 Row j -> Row j+k-m for j=m-k+1,...,m Row j -> Row j+k for j=-k+1,...,m

The result has the same size and type as x.  When isvector(x) is True,
the result is a pure vector (ndims(x) = 1).  Otherwise, the result has 2
dimensions.

@@@@examples#Examples
Examples:
  Cmd> rotate(vector(1,3,2,6,5,4),2)
  (1)           5           4           1           3           2
  (6)           6

  Cmd> rotate(matrix(vector(1,3,2,7, 6,5,4,8),4), -2)
  (1,1)           2           4
  (2,1)           7           8
  (3,1)           1           6
  (4,1)           3           5

  Cmd> rotate(vector("A","B","C","D"),-1)
  (1) "B"
  (2) "C"
  (3) "D"
  (4) "A"

@@@@caution#Caution
Caution: Do not confuse rotate() with rotation() which does rotation of
factor loadings.
@@@@______

====rotation()#multivariate analysis
%%%%
rotation(loadings [, method:Method, kaiser:T, reorder:T,
  lambda:lam,verbose:T]), where loadings is a REAL matrix, lam >= 0 is a
  real scalar and Method is a quoted string or CHARACTER scalar
%%%%
@@@@usage#Usage
L <- rotation(Loadings) or L <- rotation(Loadings, method:"varimax")
sets L to a matrix derived by varimax "rotation" from Loadings.  That
is, an orthogonal matrix R is found so that L = Loadings %*% R maximizes
a certain criterion.

Loadings must be a REAL matrix with no MISSING values and with
nrows(Loadings) >= ncols(Loadings).  The result L is a REAL matrix with
the same dimensions as Loadings.

rotation(Loadings, kaiser:T [,method:"varimax"]) does the same except
Kaiser normalization is used.  That is the rows of loadings are rescaled
to have norm 1 before rotation and then unscaled after rotation.

rotation(Loadings, method:"quartimax" [, kaiser:T]) does the same except
the quartimax criterion is maximized.

rotation(Loadings, method:"equimax" [, kaiser:T]) does the same except
the equimax criterion is maximized.

rotation(Loadings, method:"orthomax", lambda:lam [, kaiser:T]) where lam
>= is a REAL scalar does the same except the orthomax crition with
parameter lam is maximized.  lam = 1, lam = 0 and lam =
ncols(Loadings)/2 correspond to varimax, quartimax and equimax rotation,
respectively.

rotation(Loadings, verbose:T [,method:Method ...]) prints the value of
the criterion before and after rotation.

rotation(Loadings, reorder:T [,method:Method ...]) does the same except
that after rotation each column is multiplied by +1 or -1 so that the
column sum is positive, and the columns are reordered in decreasing
order of the column sums of squares.

@@@@use_with_factor_analysis#Use with factor analysis
rotation() is designed to be used to rotate a factor analysis matrix of
loadings so as to achieve "simple structure."

It is usual to rotate not the loading matrix itself, but the loading
matrix scaled so that the row sums of squared loadings are constant.
The rotated matrix is then rescaled to restore the original row sums of
squares.  This is sometimes called Kaiser normalization and is
accomplished automaticall by using 'kaiser:T' as an argument.

The rotated matrix has the form rotated_L = L %*% A, where A is m by m.
A can be recovered as
      A <- solve(L' %*% L, L' %*% rotated_L)

@@@@epsilon_and_maxiter_keywords#Keywords 'epsilon' and 'maxiter'
The algorithm used is iterative, using a default convergence criterion
of epsilon = .00001, and performing a maximum of 100 iterations.  These
values can be modified by including keyword phrases 'epsilon:value'
and/or 'maxiter:n', where value is a small positive number and n is a
positive integer.

@@@@caution#Caution
Caution: Do not confuse rotation() with rotate() which shifts the rows
of its first argument up or down, wrapping around the end.
@@@@______

====round()#transformations
%%%%
round(x [, ndec]), x REAL or a structure with REAL components, ndec an
  integer
%%%%
@@@@usage#Usage
round(x) rounds the elements of the REAL variable x to the nearest
integer, producing a vector, matrix, or array with the same shape as x.

round(x,n) where n is an integer is equivalent to 10^(-n)*round(x*10^n).
If n > 0, this rounds to n decimal places.  If n < 0, this rounds to the
nearest multiple of 10^abs(n).  round(x,0) is equivalent to round(x).

@@@@structure_argument#Structure argument
If x is a structure, so is round(x) or round(x,n).  If xi is the i-th
component of x, the i-th component of round(x) or round(x,n) is
round(xi) or round(xi,n).

@@@@example#Example
Example: round(3141.593,2) is 3141.59 and round(3141.593,-2) is 3100,
the nearest multiple of 100 = 10^2.

@@@@character_argument#CHARACTER argument
round(x, p) can also be used when x is a CHARACTER variable and p, if
present, is a quoted string or CHARACTER scalar or REAL scalar.  The
result is a CHARACTER variable of the same shape as x describing the
transformation.  For example, both round(vector("X1","X2"),3) and
round(vector("X1","X2"),"3") return vector("round(X1,3)","round(X2,3)").
Any element of x that is "" or starts with '@', '(', '[', '{', '<', '/'
or '\' is not modified.  This can be useful for creating labels for a
transformed variable.

@@@@see_also#Cross references
See also topics floor(), ceiling(), 'structures', 'labels'.
@@@@______

====rowplot()#plotting
%%%%
rowplot(x [, graphics keyword phrases]), x a REAL matrix
%%%%
@@@@usage_and_example#Usage and example
rowplot(x) makes an "interaction" plot of the data in the matrix x.  The
plotting positions are the column numbers and the values in x.  Points
within each row are joined by lines.  Any keywords useable in chplot()
may follow x.  rowplot() is implemented as a macro.

If option 'dumbplot' has been set False (see subtopic
'options:"dumbplot"'), the plot will be a low resolution plot unless
'dumb:F' is an argument.

You can use all the usual graphics keywords, including 'title', 'xlab',
'ylab', and 'file'.  See topics 'graphs', 'graph_keys', 'graph_border'
and 'graph_ticks'.

Example:
  Cmd> rowplot(run(20)^(.2*run(5)'),\
        title:"X^vector(.2, X^.4, X^.6, X^.8, X)'")

@@@@see_also#Cross references
See also topic colplot().
@@@@______

====rpoi()#random numbers
%%%%
rpoi(n,lambda), n positive integer, lambda scalar >= 0 or non-negative
  vector of length n.
%%%%
@@@@usage#Usage
rpoi(N,lambda) generates a vector of N independent Poisson pseudo-random
variables with mean lambda.  N must be a positive integer.

lambda must be a REAL scalar >= 0 or a REAL vector of length N with
lambda[i] >= 0.  If lambda is a scalar, it is used for every element of
the result.  Otherwise, element of the result will be Poisson with mean
lambda[i].

@@@@generating_negative_binomial#Generating negative binomial
When used together with invgamma(), rpoi() can be used to generate
pseudo-random negative binomial random variables.

  Cmd> y <- rpoi(N, m*invgamma(runi(N),alpha)) # m > 0, alpha > 0

will generate negative binomial random variables with shape or index
alpha and mean alpha*m, with probabilities
 p[y=x]={(1-m)^alpha}*alpha*(alpha+1)...*(alpha+x-1)*m^x/x!, x=0,1,... .

@@@@initializing#Initializing
If the random number generator has not been initialized by setseeds(),
setoptions() or previous use of rbin(), rnorm(), rpoi() or runi(), the
generator's "seeds" will be initialized automatically using the current
time and date, and their values will be printed out.

@@@@reference#Reference
The algorithm is based on C. D. Kemp and A. W. Kemp, Appl Statist 40
(1991) 143-158.

@@@@see_also#Cross references
See also setseeds(), getseeds(), setoptions(), runi(), rnorm(), rbin(),
invgamma(), cumpoi(), subtopic 'options:"seeds"'.
@@@@______

====rsample()#random numbers
%%%%
y <- rsample(x,n) or y <- rsample(x,n,T), REAL vector or matrix x,
  positive integer n
y <- rsample(x,n,F) requires n <= nrows(x)
%%%%
@@@@purpose#Purpose
rsample() is a macro you can use to select a random sample with or
without replacement from the rows of a REAL matrix or vector.

@@@@usage#Usage
y <- rsample(x, n) and rsample(x, n, T) both select a random sample of
size n from the rows of REAL matrix x.  n is a positive integer.
Sampling is *with* replacement.

y <- rsample(x, n, F) does the same, except that sampling is without
replacement.  It is an error if n > nrows(x).

In both usages, y will be a REAL vector of length n or a REAL n by
ncols(x) matrix.

@@@@example#Example
The following selects a random sample of size 5 drawn without
replacement from {1,2,...,20}:

  Cmd> y <- rsample(run(20),5,F)

  Cmd> y
  (1)          11          10           8           3          18

@@@@see_also#Cross references
See also runi(), rnorm().
@@@@_____

====rsolve()#linear algebra
%%%%
rsolve(A, B [,quiet:T]), A a square REAL matrix, B a REAL matrix,
  nrows(A) = ncols(B).
%%%%
@@@@usage#Usage
rsolve(a, b) computes the solution x to the system of linear equations
x a = b, where a is a REAL square matrix and b is a REAL matrix with
ncols(b) = nrows(a).  rsolve(a, b) produces the same result as
solve(a',b')', and is mathematically but not computationally equivalent
to b %*% solve(a).

If a is singular, an informative message is printed and the operation
aborts.

MISSING values are not allowed in a or b.

When a has labels, the row and column labels of rsolve(a,b) are the row
labels of b and respectively.  If b does not have labels, the rowlabels
of solve(a,b) are rep("a", nrows(b).  See topic 'labels'.

Expression b %/% a is equivalent to rsolve(a, b).

@@@@quiet_keyword#Keyword 'quiet'
Occasionally, "overflow" occurs during the computation.  Any values in
the result that are too large to be represented are replaced by MISSING
and a WARNING message is printed.  You can suppress the message by
including 'quiet:T' as an argument.  If you do, you should use
anymissing() to check the result for the presence of MISSING elements.

@@@@see_also#Cross references
See also solve(), swp().
@@@@______

====run()#combining variables,variables
%%%%
run(first,last,incr) or run(first,last) or run(last)
%%%%
@@@@usage#Usage
run(First,Last,Incr) will generate a sequence of numbers from First to
Last with step size given in Incr.  The i-th number is computed as
First+(i-1)*Incr (unless it is very close to 0 or Last; see below).  It
is an error if Incr is 0, unless First = Last.

run(First,Last) is the same as run(First,Last,1) if Last > First, and to
run(First,Last,-1) if Last < First.

run(n) does the same as run(1,n) if n is an integer.  This is the most
common usage.

run(vector(First,Last,Incr)) is the same as run(First,Last,Incr).  A
vector argument must be of length 3, so run(vector(First,Last)) is
illegal.

@@@@values_computed_exactly#Values computed exactly
When Incr is (Last-First)/n, where n is an integer, there will be n+1
values, with the (n+1)-th being exactly Last, even if First+n*Incr is
slightly less or greater than Last because of rounding error.

Similarly, if 0 is between First and Last and Incr is -First/n, the
(n+1)-th value will be exactly 0 even if First+n*Incr is not exactly 0
because of rounding error.  In both situations, the value is rounded to
the target value (Last or 0) if abs((First+n*Incr-target)) <
1e-15*abs(Last-First).
@@@@______

====runi()#random numbers
%%%%
runi(n), n a positive integer
%%%%
@@@@usage#Usage
runi(count) generates a vector of count pseudo-random uniforms on the
interval 0 to 1.

If the random number generator has not been initialized by setseeds(),
setoptions() or previous use of rbin(), rnorm(), rpoi() or runi(), the
generator's "seeds" will be initialized automatically using the current
time and date, and their values will be printed out.

You can generate uniform random variables on the interval (a,b), a < b
by
  Cmd> x <- a + (b - a)*runi(n)

@@@@discrete_uniform_generation#Discrete uniform generation
You can generate the discrete uniform distribution on the integers 1, 2,
..., m by
  Cmd> x <- ceiling(m*runi(n))

This is helpful when sampling with replacement from the rows of a data
vector of matrix.

@@@@nonuniform_random_variable_generation#Nonuniform random variable generation
When Q() is a macro or function computing the quantile function (inverse
cumulative distribution function) of a continuous random variable
(invnor() or invchi()) for example), Q(runi(n) [,parameters]) generates
a random sample from that distribution.

  Cmd> invstu(runi(5),3) # Student's t on 3 d.f.
  (1)     0.43734     0.34297    0.054439  -0.0017229    -0.32894

  Cmd> invF(runi(5),5,30) # F on 5 and 30 d.f.
  (1)     0.45207      2.2247     0.52716     0.29218       1.506

The functions that you can use directly this way are invbeta(),
invchi(), invF(), invgamma(), invnor(), and invstu().  In principle you
could also use invdunnett() and invstudrng(), but that is not advisable
because they are so computationally intensive.

@@@@see_also#Cross references
See also topics setseeds(), getseeds(), setoptions(), rnorm(), rbin(),
rpoi(), subtopic 'options:"seeds"'
@@@@______

====samplesize()#probabilities,glm,anova
%%%%
samplesize(noncen,ngrp,alpha,Pwr[,design:"rbd"][,maxn:N]), noncen > 0,
  0 < alpha < 1, 0 < Pwr < 1, integers ngrp > 0, N > 0
%%%%
@@@@usage#Usage
samplesize(noncen,ngrp,alpha,Pwr) computes the group sample size (number
of replicates) required in a balanced one-way analysis of variance
(completely randomized design with equal group sizes) of ngrp groups at
significance level alpha to achieve power Pwr.

Argument noncen is the noncentrality parameter and is interpreted as
sum(alpha^2)/sigma^2, where alpha is a vector of treatment effects with
sum(alpha) = 0 and sigma is the error standard deviation.

If the required sample size exceeds 256, 256 is returned.

samplesize(mu^2/sigma^2,1,alpha,Pwr) returns the sample size required to
achieve power Pwr in a single-sample two-tail t-test of H0: mu = 0 when
the standard deviation is sigma.

@@@@design_and_maxn_keywords#Keywords 'design' and 'maxn'
samplesize(noncen,ngrp,alpha,Pwr,design:"rbd") computes the number of
blocks required to achieve power Pwr in a randomized complete block
design with ngrp >= 2 treatments.

samplesize(noncen,ngrp,alpha,Pwr [,design:"rbd"], maxn:N), N > 0 an
integer, does the same, except if the required samples size exceeds N, N
is returned.

@@@@see_also#Cross references
See also power() and power2().
@@@@______

====save()#files,general,variables,null variables
%%%%
save(FileName [,all:T, v335:T, v406:T, nulls:F, options:F,\
  history:T, ascii:T])
save() repeats previous save() or asciisave()
%%%%
@@@@usage#Usage
save(FileName) saves the MacAnova "workspace", that is, all the current
variables and option values, in a file with name given in the quoted
string or CHARACTER variable FileName.  The file will be in a binary
format that is specific to the type of computer.  The workspace can be
recovered later by restore().  See topics 'files', 'workspace',
restore().

save(FileName,ascii:T) is equivalent to asciisave(FileName), that is,
the file written will be an ASCII text file instead of a binary file.
This option can be used together with others described below.

In a version with windows, FileName can be "", in which case you will
be prompted for the file name.

@@@@resaving_in_same_file#Resaving in same file
save(), with no file name, saves the workspace in the same file as
specified in a previous asciisave() or save().  If the previous save was
ASCII, so will be the current save.  Moreover, if the previous save()
specified an obsolete format (see below), the same format will be used,
unless explicitly changed.  If there was no previous save() or
asciisave(), omitting the file name is an error.

@@@@partial_save#Partial save
save(FileName, var1, var2, ....) does a partial save, saving only
variables or macros var1, var2, ... on the file.  Any variable to be
saved that is specified in keyword form (example: save(FileName,
residuals:RESIDUALS)), will be restored having the keyword name.  Unless
the variables are saved using an obsolete format, when a partial
save is restored, other variables are not affected.  If an obsolete
format is used, other variables are normally deleted when the file is
restored, unless keyword phrase delete:F is used on restore().

@@@@saving_GRAPHWINDOWS#Saving GRAPHWINDOWS
On all versions, a complete save, but not a partial save, normally saves
the special structure GRAPHWINDOWS (see topic 'GRAPHWINDOWS') as part of
the workspace.  When GRAPHWINDOWS is restored, windows corresponding to
any GRAPH components are redrawn.

save(FileName, graphwind:F) saves the workspace without including
GRAPHWINDOWS.

@@@@saving_history_of_commands#Saving history of commands
A complete save (but not a partial save) normally saves the history. 
When restore() recovers the information in the file, the saved history
list replaces the command history unless restore() keyword phrase
'delete:F' is used.

save(FileName,history:F) saves the workspace without saving the command
history.

save(FileName,history:T) saves the workspace together with the command
history, even when the value of option 'savehistry' is False (see topic
'options':"savehistry"').  'history:T' is illegal on a partial save.
See sethistory() and gethistory().

@@@@saving_options#Saving options
save(FileName,options:F) suppresses saving the current values of
options, which normally occurs.  When options:F is not used, restore()
resets options to the saved values, including random number seeds.  See
setoptions(), getoptions().

You can use any of history:F, options:F and graphwind:F together.

@@@@save_glm_private_information#Save GLM private information
save(FileName,all:T) saves, in addition to the workspace, a variety of
information computed by the last GLM command.  When this information is
recovered by restore(), it becomes possible to use functions such as
secoefs() and modelinfo() to get information on the last GLM analysis
before the save.

This option is really useful only when you have just completed a GLM
(generalized linear or linear model) computation (regress(), anova(),
poisson(), etc.) that took a long time to compute since it is usually
sufficient just to repeate the GLM command when you restore the
workspace.  If the model was complex and had many cases, 'all:T' can
greatly increase the size of the workspace file.

@@@@nulls_keyword#Keyword 'nulls'
save(FileName, nulls:F [, var ...]) does not save NULL variables.  See
topic 'NULL'.

@@@@other_information_saved#Other information saved
save() also saves the current time and date.  These are reported by
restore() when the workspace or variables are restored.

In addition, save() saves information about the computer MacAnova is
running on and the compiler it was compiled with, plus information about
the internal representation of linear models.  This information is used
by restore() to determine if it is safe to restore variables.  If you
are planning to restore the file on another computer or different
version of MacAnova, use asciisave().

@@@@difference_from_asciisave#Difference from asciisave()
save() differs from asciisave() in that asciisave() saves the
information in the form of a "text" file, more or less human readable,
that can be transferred between different types of computers.  Files
created by asciisave() are often bigger than the corresponding file
created by save().

@@@@why_use_save#Why use save()
save() and asciisave() are useful when a session must be interrupted and
you don't want to lose what you have done.  On an unstable system or
when using MacAnova remotely over a noisy phone line, a useful insurance
measure is to save your current variables every few minutes.  The
following creates a macro that makes this easy:
  Cmd> snapshot <- macro("save(\"snapshot.sav\",all:T)")

Then simply typing 'snapshot()' saves a copy of your workspace, options,
and internal variables related to GLMs on file snapshot.sav.  They can
be restored by 'restore("snapshot.sav")'.

@@@@examples#Examples
Examples:
  Cmd> save("chckpnt.bin") # save entire workspace, but not GLM stuff
  Cmd> save("chckpnt.bin",options:F,history:)#no history or options
  Cmd> save("saveFile",all:T) # save everything, including GLM stuff
  Cmd> asciisave("saveFile",x,y,residuals:RESIDUALS, v31:T)
  Cmd> save("saveFile",x,y,residuals:RESIDUALS, v31:T, ascii:T)

The last two are identical and save only x, y, and RESIDUALS on ASCII
file saveFile readable by MacAnova 3.1.  When restored, RESIDUALS will
be recreated with name 'residuals'.

@@@@windowed_versions#Windowed versions
In windowed versions, Save Workspace on the File menu (Command+K or
Ctrl+K) is equivalent to 'save()', except that if there hasn't been a
previous save() or asciisave(), you are prompted for a file name using
the usual file navigation dialog box.

When you Quit from MacAnova, you are normally asked if you want to save
the workspace (only in windowed versions).

@@@@backward_compatibilitye
          Compatibility of workspace files of earlier versions
There have been minor and major changes in workspace file format as
MacAnova has evolved.  Generally when a change is made, older versions
of MacAnova are not able to restore files created using the new format.
For instance, workspace files written by version 3.36 or later which
contain NULL variables or variables with MISSING values cannot be
restored by earlier versions.

If it is important for an earlier version of MacAnova to be able to
restore a workspace file created on the latest version, you can specify
one of the obsolete formats by using keywords 'v24', 'v31', 'v335' or
'v406'.

save(FileName,v24:T [, var ...]) or save(FileName,old:T [, var ...])
saves in the format recognized by versions 2.4x and earlier of MacAnova.
Keywords all and options are ignored and options are not saved.

save(FileName,v31:T [, var ...]) saves in the format recognized by
versions 3.0 and 3.1x of MacAnova.

save(FileName,v335:T [, var ...]) saves in the format recognized by
version 3.35 of MacAnova.  NULL variables are not saved.

save(FileName,v406:T [, var ...]) saves in the format used in versions
later than 3.35 but earlier than 4.07.  Information on ticks in GRAPH
variables is not saved and there are other differences.  Use v406:T when
creating a workspace file that is to be read by MacAnova 4.06 or
earlier.

Note: Prior to version 4.01, names starting with '_' were not permitted.
Variables with such names can be restored by earlier versions, but they
cannot be used.

@@@@see_also#Cross references
See also topics asciisave(), restore(), 'options', 'files'
@@@@______

====scalars#variables,syntax
%%%%
Create a scalar variable: x <- 3.1415927; c <- "Hi, I'm Frank"; no <- F
%%%%
@@@@description#Description
A scalar variable is a vector of length 1.  It can be REAL, LOGICAL or
CHARACTER.  It consists of one item of information.

For practically all purposes, a matrix or array all of whose dimensions
are 1 (matrix(sqrt(2), 1), for example) is also considered to be a
scalar variable.

@@@@examples#Examples
You can create scalar variables in many ways.  Here are some examples.

  Cmd> sqrt2 <- sqrt(2); twopi <- 2*PI # REAL

  Cmd> bananas <- 7; cost <- prices[bananas]*3.1 # REAL

  Cmd> filename <- "babydata.txt"; today <- weekdays[5] # CHARACTER

  Cmd> fitmean <- F; expensive <- prices[bananas] > .49 # LOGICAL

In the third example, "babydata.txt" is an example of what is often
called a quoted string - character information enclosed between two
double quotation marks.

@@@@see_also#Cross references
See topics 'file_names' for the use of CHARACTER scalars as file names.

See topics 'variables', 'arithmetic' and 'transformations' for more
information about the use of scalar variables.
@@@@______

====screen()#glm,regression
%%%%
screen([Model] [, method:"cp" or "rsq" or "adjrsq", mbest:m, forced:fn,\
  s2:mse, penalty:pen, keep:items]), m positive integer, fn vector of
  positive integers, mse and pen positive REAL scalars, items CHARACTER
  scalar or vector with elements "p", "cp", "rsq", "adjrsq", "model",
  "intmodel" or "all".
%%%%
@@@@usage#Usage
screen(Model) screens all the regression models based on one or more of
the X variables given in the CHARACTER argument Model.  The best of
these models are printed, together with the values of Mallow's Cp =
RSS/MSE + 2*p - n, multiple R^2 = coefficient of determination, and
adjusted R^2 = 1 - (n-1)*(1-R^2)/(n-p), where p is the number of
coefficients in the model, including the constant term.

In the definition of Cp, RSS is the residual sum of squares for a model
and MSE is either the residual mean square from the model using all the
variables or the value of optional keyword 's2'.  When optional keyword
'penalty' is used, its value replaces 2 as multiplier of p in the
definition of Cp.  See below for details on 's2' and 'penalty'.

By default, screen() finds the models with the 5 smallest values of
Mallow's Cp statistic.  This default can be changed by keywords 'method'
and 'mbest'; see below.

Model must not specify a model with no constant term.  For example,
screen("y=x1+x2+x3-1") is illegal.  See topic 'models' for information
on the form of Model.

@@@@keep_and_print_keywords#Keywords 'keep' and 'print'
screen(Model, keep:Items) does the same, except that nothing is printed.
Instead information specified by CHARACTER scalar or vector Items is
returned as the value of screen().   See below for permissible values.

screen(model, keep:Items, print:T) both prints the results and returns
those results specified by Items.

                Permissible values of elements of Items:
  "p"        Number of coefficients fit including constant (intercept)
  "cp"       Mallow's Cp statistic
  "rsq"      Multiple R^2
  "adjrsq"   Adjusted R^2
  "model"    Models selected in the CHARACTER form expected by regress()
  "intmodel" Integer Matrix with each column containing the indices of
             the variables in one of the selected models
  "all"      All of the above

The values produced by the first 5 of these are vectors with one element
for every model selected; "intmodel" produces a matrix with one column
for every model selected and nv rows, where nv is the number of
independent variables in Model.

When more than one item is specified, they are returned as components of
a structure with names as in this list.

@@@@details_on_value#Details on value
vector("y=x1","y=x1+x3+x4","y=x2+x3+x4","y=x1+x2","y=x4") would be
an example of a CHARACTER vector that might be produced by keep:"model".
For this case, if there are 4 variables in all in the obvious order, the
"intmodel" value would be the matrix
                          [ 1   1   2   1   4]
                          [ 0   3   3   2   0]
                          [ 0   4   4   0   0]
                          [ 0   0   0   0   0]

@@@@other_keywords
                             Other Keywords
 Keyword  Type of value           Default            Meaning
  method  CHARACTER variable        "cp"  Criterion ("cp", "rsq", or
                                          "adjrsq") for subset selection

  mbest   Positive integer            5   Number of subsets to be found

  forced  REAL Vector of positive   none  List of independent variables
          integers or independent         to be forced into all subsets
          variable names

  s2      Positive REAL number       MSE  Replacement for full model
                                          MSE in computing Cp

  penalty Positive REAL number        2   Multiplier of p in computing
                                          Cp

  print   T or F                          print:T forces printing when
                                          'keep' is used.

Keyword 'silent', 'fstats', and 'pvals' are illegal for screen(), and
'print:F' is illegal unless keyword 'keep' is used.

@@@@method_keyword#Keyword 'method'
The value of keyword 'method' determines the criterion to be used to
rank regressions.
    Value       Criterion Used   What is better
     "cp"        Mallow's Cp      Smaller
     "rsq"       Multiple R^2     Larger
     "adjrsq"    Adjusted R^2     Larger

@@@@mbest_keyword#Keyword 'mbest'
The number of subset regressions computed is determined by the value of
'mbest'.

With method:"adjrsq" or method:"cp", exactly mbest regressions are
printed or returned.

With method:"rsq", for each possible number m, m = 1, 2, ..., nv, of
variables, screen() selects the mbest models with largest value of R^2,
where nv is the number of variables in the model.  Thus in this case, up
to (nv-1)*mbest + 1 models would be selected.

@@@@forced_keyword#Keyword 'forced'
The value of 'forced' should be a list of names of any variables that
should be forced into the model.  For instance, with forced:vector("x1",
"x2"), all models examined would include x1 and x2.  By default, no
variables are forced.  The value of 'forced' can also be a vector of
integers, say forced:vector(1,2).

@@@@penalty_and_s2_keywords#Keywords 'penalty' and 's2'
The value of 'penalty' is used to compute Cp = RSS/MSE + penalty*p - n.
Larger values increase the "penalty" of including additional variables
and tends to produce models with fewer variables.  The default value is
2.

The value of 's2' is the MSE to be used in computing Cp.  If not
specified, the mean square error from the complete model is used.

@@@@examples#Examples
        Examples, all assuming Model is "y=x1+x2+x3+x4+x5+x6+x7"

Screen with defaults mbest = 5,method = "cp",and penalty = 2
  Cmd> screen(Model)

Screen for 10 best models using adjusted R^2 with variable x3 forced
into the model:
  Cmd> screen(Model,mbest:10,forced:"x3",method:"adjrsq") # or forced:3

Screen using Cp over models with x6 forced in and penalty factor of 3:
  Cmd> screen(Model,forced:"x6",penalty:3)

Screen using defaults, saving p, cp, and the models, and printing
results:
  Cmd> result <- screen(Model,keep:vector("p","cp","model"),print:T)

  Cmd> regress(result$model[1]) # compute regression with best model

@@@@reference#Reference
screen() uses a branch and bound algorithm due to Furnival and Wilson.
See their paper, Regression by Leaps and Bounds, Technometrics 16 (1974)
499-511.

@@@@see_also#Cross references
See also regress() and anova().
@@@@______

====secoefs()#glm,anova,regression,confidence intervals
%%%%
secoefs([Term] [, errorTerm:ErrorTerm, byterm:F, se:F or coefs:F,
  silent:T]), Term a CHARACTER scalar, a positive integer, or a factor
  or variate in the current GLM model, ErrorTerm a CHARACTER scalar or
  positive integer.  byterm:F only when Term, se:F and coefs:F omitted
%%%%
@@@@usage#Usage
secoefs(Term) returns the model effects or regression coefficients and
their standard errors for the term specified in the CHARACTER variable
Term.  The result is a structure with components 'coefs' and 'se'.

The coefficients and standard errors pertain to the results of the most
recent GLM (generalized linear or linear model) command such as
regress(), anova(), or poisson().

When Term is a main effect term, the components are vectors.  When it is
an interation term, the components are matrices or arrays with the
leftmost subscript corresponding to the leftmost factor in Term.

Caution: After anova(), manova() and regress(), standard errors are
computed using the final error mean square in the model.  This may not
be appropriate with mixed models, including split plot designs.

@@@@specifying_the_term#Specifying the term
Term is usually a quoted string or CHARACTER variable such as "a.b"
which exactly matches a term in the most recent model, that is, "a.b" is
not the same as "b.a".  An interaction term produces a matrix or array
with the leftmost subscript corresponding to the leftmost factor in
Term.

If any variables in Term originally specified in the form {expr}, where
expr is a MacAnova expression, you must include the enclosing '{' and
'}'.

For a term which consists of a single factor or variate, Term can be its
unquoted name.

Alternatively, Term can be a integer between 1 and the number of terms,
excluding the final error term.  For example, unless the model contained
"-1", secoefs(1) gets the estimated intercept or grand mean and its
standard error.

@@@@no_term_specified#No term specified
secoefs() (no Term specified) computes coefficients and standard errors
for all terms in the model.  The result is a structure with one
component for each term in the model, with each component itself a
structure with components 'coefs' and 'se'.

The names of the top level components in the result are taken from the
names of the terms, truncated if necessary to 12 characters.  When
such truncation is neccessary, the result is also given labels which
contain the full component names.  See topic 'labels'.

secoefs(byterm:F) is the same as secoefs() except that the resulting
structure has two components, 'coefs' and 'se', each of which is a
structure with one component per term (unless there is only one term in
the model).  In this case, the names of the bottom level components are
taken from the possibly truncated names of the terms.  When any
truncation takes place, the full term names are also attached as labels.

@@@@silent_keyword#Keyword 'silent'
secoefs(Term, silent:T) and secoefs(silent:T) do the same, but certain
warning and advisory messages are suppressed.  'silent:T' can be used
with any other keywords.  This feature is useful in a macro when warning
messages might confuse the user, or in a simulation.  The default value
of 'silent' is False unless the value of option' 'warnings' is False.

@@@@suppressing_coefficients_or_standard_errors#Suppressing coefficients or standard errors
secoefs(Term,coefs:F) and secoefs(coefs:F) (or secoefs(,coefs:F))
suppress the computation of the coefficients, returning a structure or
matrix containing only standard errors.  secoefs(Term,se:F) and
secoefs(se:F) are equivalent to coefs(Term) and coefs(), respectively.

You can compute a structure containint t-statistics for every
coefficient by
  Cmd> tt <- secoefs(se:F)/secoefs(coefs:F) #or coefs()/secoefs(coefs:F)

Alternatively, you could compute such a structure by
  Cmd> @tmp <- secoefs(byterm:F); tt <- @tmp$coefs/@tmp$se

@@@@after_manova#After manova()
secoefs(Term,Varno) or secoefs(,Varno) computes coefficients and
standard errors only for variable number Varno in the case of a
multivariate dependent variable.  If present, Varno must be the second
argument and any keywords must follow it.

@@@@specifying_error_term#Specifying error term
For all forms, an optional keyword phrase argument errorterm:ErrTerm or
errorterm:ErrTermNo, where ErrTerm is a CHARACTER variable or quoted
string specifying a term in the model and ErrTermNo is a positive
integer, specifies that the MS from the indicated term is to be used in
computing standard errors.

@@@@confidence_intervals#Confidence intervals
If tcrit is a critical value, say, invstu(1-alpha/2,errorDF), you can
compute the lower 1-alpha confidence limits for the coefficients
  Cmd> @tmp <- secoefs(byterm:F);@tmp$coefs - tcrit*@tmp$se
and similarly for upper limits (replace - by +).

@@@@example#Example
After anova("y= a + b + a.b")
   secoefs(a), secoefs("a"), or secoefs(1) will compute the main effect
     coefficients and their standard errors for factor a
   secoefs(a,coefs:F), secoefs("a",coefs:F), or secoefs(2,coefs:F) will
     compute the standard errors of main effect coefficients
   secoefs("a.b") or secoefs(4) will produce matrices of the a by b
     interaction coefficients and their standard errors.
   secoefs() will produce all coefficients and their standard errors in
     a structure with components CONSTANT, a, b, and a.b.
   secoefs(byterm:F) will produce all coefficients and their standard
     errors in a structure with components coefs and se

This will produce the a by b interaction effects and their standard
errors.

@@@@limitations#Limitations
Secoefs() does not work after fastanova(), ipf(), or screen(), or if
'coefs:F' was an argument to the most recent GLM command.

@@@@see_also#Cross references
See also coefs(), contrast(), modelinfo(), popmodel(), pushmodel().
@@@@______

====select()#combining variables,variables
%%%%
select(k, x), k vector of positive integers or LOGICAL vector, x a
  matrix.
%%%%
@@@@usage#Usage
select(k, x) computes vector(x[1,k[1]],x[2,k[2]],...,x[n,k[n]]), where n
= nrows(k).  For example, select(k,x)[i] is x[i,k[i]], the k[i]-th
element of the i-th row of x. The length of the result is nrows(k).

k must be a REAL vector of positive integers or a LOGICAL vector and x
must be a matrix with nrows(x) >= nrows(k) and ncols(x) >= max(k),

When k is a LOGICAL vector, False is translated to 1, and True is
translated to 2.  For example, when x is a matrix with two columns,
select() can be used to select column 1 or column 2 of x depending on
whether k[i] is False or True.  NOTE: This differs from home LOGICAL
subscripts are interpreted.  See 'subscripts'

If k[i] is MISSING, select(k,x)[i] is MISSING when x is LOGICAL or REAL
and is "" when x is a CHARACTER variable.

When x is REAL or LOGICAL and k has no MISSING values, select(k, x) is
equivalent to vector(x[hconcat(run(nrows(k)), k)]).

@@@@see_also#Cross references
See topic 'subscripts'.
@@@@______

====sethistory()#general
%%%%
sethistory(lines), lines is a CHARACTER vector with length <= value of
  option 'history'
%%%%
@@@@usage#Usage
sethistory(Lines), where Lines is a CHARACTER vector, resets the
internal list of previous commands to Lines with Lines[1] the earliest
command available.  Subsequent keyboard or menu retrieval of previous
commands will retrieve elements of Lines.

It is an error if length(Lines) > nHist, where nHist is the value of
option 'history'.  See subtopic 'options:"history"'.

sethistory() is not implemented in the limited memory DOS version or in
any version that does not allow keyboard or menu retrieval of previous
commands.

@@@@see_also#Cross references
See gethistory() for an example using gethistory() and sethistory() to
maintain a history of commands executed between MacAnova sessions.
@@@@______

====setlabels()#general,variables
%%%%
setlabels(x, labels [,silent:T]), x an existing scalar, vector, matrix,
  array or structure, labels a CHARACTER scalar or vector, a structure
  with CHARACTER scalar or vector components, or NULL
%%%%
@@@@usage#Usage
setlabels(x, Labels) "attaches" coordinate or component labels in Labels
to variable x.  If x already has labels, they are replaced.  Labels must
a CHARACTER scalar or vector, a structure whose components are CHARACTER
scalars or vectors, or NULL.

x must be an existing scalar, vector or array of any type, or a
structure.

When Labels is NULL, any existing labels for x are removed.

When x is a vector, Labels normally is a scalar or vector of row labels
for x.  When x is a matrix or array, Labels is normally a structure with
ncomps(Labels)) = ndims(x) with Labels[I] a scalar or vector used to
label dimension I of x.

setlabels(x, Labels, silent:T) does the same, except messages
concerning a mismatch in the number of vectors of labels provided are
suppressed.

@@@@wrong_number_of_labels#Wrong number of labels
It is an error when the length of a non-scalar vector of labels for a
coordinate does not match the dimension of the coordinate.  See topic
'labels' for information on how scalar coordinate labels are
interpreted.

When Labels is a vector and ndims(x) > 1 or labels is a structure with
ndims(x) > ncomps(Labels), the missing labels are all assumed to be "@".

Conversely, when Labels is a structure and ncomps(Labels) > ndims(x),
the extra vectors of labels are ignored.

@@@@see_also#Cross references
See also topics 'labels', getlabels(), haslabels().
@@@@______

====setodometer()#general,macros
%%%%
odometer <- setodometer([lower:L,] upper:U [,ndigits:M, ] [,place:N]),
  L and U integer scalars or vectors, integer M > 0, N >= 0
odometer <- setodometer(odometer, place:N), odometer a structure with
  integer components 'digits', 'lower', 'upper', 'place'
odometer <- setodometer(odometer [,step:n]), integer n, default 1
%%%%
@@@@what_is_an_odometer
                       Description of an odometer
setodometer() is used to create or modify an "odometer".  An odometer is
a structure of the form

  structure(digits:D, lower:L, upper:U, place:N)

where D is a vector of M integers and L and U are integer vectors of
length M or scalars.  D, L and U satisfy L[i] <= D[i] <= U[i], where L
and U are interpreted as rep(L, M) and rep(U, M) when they are scalars.

See topics 'scalars', 'vectors' and 'structures' for information on
these types of variables.

See below for how to use setodometer() to create, set and advance an
odometer.

@@@@details#Details
In the following, when L and/or U are scalars, L[i] and U[i] should be
interpreted as L and/or U (rep(L,M)[i] and/or rep(U,M)[i]).

Note: L[i] = U[i] is permitted.

An odometer is modeled on the distance display in an automobile, with
the M elements of D corresponding to the digits in the display.  It
differs in that D[i] runs from L[i] to U[i] instead of from 0 to 9, and
the digits are in reverse order (D[1] is the least significant, D[M] is
the most significant).  N corresponds to the distance traveled.  When N
= 0, D = vector(L[1], L[2], ..., L[M]) (rep(L,M) when L is a scalar).

Let I = D - L and let R = U - L + 1 (rep(U - L + 1, M) when U and L are
scalars) and define Size = prod(R).

When 0 <= N < Size, the elements of I are the 'digits' of N in a mixed
radix representation with radices R[i], in reverse order.  For example,
when M = 3, N = I[1] + I[2]*R[1] + I[3]*R[1]*R[2].  When L = 0 and U =
m-1 are scalars, the elements of I are the base m digits of N, in order
from least to most significant.  When N < 0 or N >= Size, the elements
of I are the digits of N modulo Size (N - Size*floor(N/Size)).

@@@@creating_an_odometer
                          Creating an odometer
O <- setodometer(lower:L, upper:U, ndigits:M) creates an odometer O.  M
> 0 must be an integer, and L and U must be integer scalars or vectors
of length M, with a scalar L or U interpreted as rep(U,M) or rep(L,M).
L and U must satisfy L[i] <= U[i], R[i] = U[i] - L[i] + 1 < 2^31, and
Size = prod(R) < 2^52.  These limits may be different on some computer
systems.

Component 'digits' is initialized to L (or rep(L,M) when L is a scalar).
Components 'lower' and 'upper' are initialized to L and U, respectively,
and component 'place' is initialized to 0.

O <- setodometer(lower:L, upper:U), without 'ndigits:M', is equivalent
to O <- setodometer(lower:L,upper:U,ndigits:max(length(L),length(U))).

O <- setodometer(upper:U [,ndigits:M]) is equivalent to O <-
setodometer(lower:0, upper:U [,ndigits:M]); that is, the default value
for 'lower' is 0.

O <- setodometer([lower:L,] upper:U [,ndigits:M], place:N) does the
same, except O$place is set to N and O$digits is set to L + mixed radix
digits of N.  N must satisfy 0 <= N < Size = prod(U-L+1).

@@@@setting_and_advancing_an_odometer
                   Setting and advancing an odometer
O1 <- setodometer(O, place:N) is equivalent to O1 <-
odometer(lower:O$lower,upper:O$upper,ndigits:length(O$digits), place:N);
that is, it creates an odometer O1 with the same L and U as O, but at
place N.

O1 <- setodometer(O, step:n), where O is an odometer and n is an
integer, creates an odometer O1 with O1$place = O$place + n.  O1$digits
is computed by stepping O$digits forward n steps when n >= 0, or
backward by -n steps when n < 0.  n must satisfy abs(n) < Size =
prod(U-L+1).  When abs(n) is large, this may take some time since it is
computed as a sequence of single forward or backward steps.

O1 <- setodometer(O) is equivalent to O1 <- setodometer(O, step:1); that
is the odometer is advanced by 1.

When 0 <= O$place + n < Size, setodometer(O, step:n) is equivalent to
setodometer(O, place:O$place + n), except that setodometer(O, step:n)
can be much slower when abs(n) is large.

@@@@examples#Examples
Examples:
 Step through the various factor combinations of a 2^k design:
   Cmd> counter <- setodometer(upper:1,ndigits:k) #lower is 0

   Cmd> for(i,run(2^k)){
          levels <- counter$digits
          # do something with levels
          counter <- setodometer(counter);; # step by 1
        }

 Find hexadecimal representation
   Cmd> N <- 9 + 3*16 + 11*16^2 + 15*16^3; N
   (1)       64313

   Cmd> O <- setodometer(upper:15,ndigits:8,place:N); O # lower is 0
   component: digits
   (1)           9           3          11          15           0
   (6)           0           0           0
   component: lower
   (1)           0
   component: upper
   (1)          15
   component: place
   (1)       64313

   Cmd> letters <- vector("0","1","2","3","4","5","6","7","8","9",\
       "A","B","C","D","E","F")

   Cmd> paste(letters[reverse(O$digits)+1],sep:"")
   (1) "0000FB39"

   Cmd> O <- setodometer(lower:1,upper:16,ndigits:8,place:N); O #lower 1
   component: digits
   (1)          10           4          12          16           1
   (6)           1           1           1
   component: lower
   (1)           1
   component: upper
   (1)          16
   component: place
   (1)       64313

   Cmd> paste(letters[reverse(O$digits)],sep:"") # +1 not needed now
   (1) "0000FB39"

 Macro to find binary bits of integer from most to least significant
   Cmd> bits <- macro("@N <- argvalue($1,\"N\",\"pos int scalar\")
      @ndigits <- ceiling(log(@N+1)/log(2))
      reverse(setodometer(upper:1,ndigits:@ndigits,place:@N)$digits)")

   Cmd> bits(N)
    (1)           1           1           1           1           1
    (6)           0           1           1           0           0
   (11)           1           1           1           0           0
   (16)           1

@@@@see_also#Cross references
See also paste(), prod(), reverse(), max(), macro(), 'macros',
'macro_syntax'.
@@@@______

====setoptions()#control,missing values,output,random numbers
%%%%
setoptions(option1:value [,option2:value ... ] [,badoptok:T]) option1,
  option2, ... option names
setoptions(str [,badoptok:T]), where str is of the form
  structure(option1:value, ...)
Type 'usage(options)' for a succinct list of all options and their
   permissible values.
%%%%
@@@@usage#Usage
setoptions(keyword:value [,keyword:value, ...]) changes the values of
various items specified by the keywords.

Legal option names are 'angles', 'batchecho', 'dumbplot', 'errors',
'findmacros', 'format', 'fstats', 'height', 'inline', 'labelabove',
'labelstyle', 'maxlinelen', 'maxwhile', 'minpvalue', 'missing', 'nsig',
'prompt', 'pvals', 'quiet', 'restoredel', 'seeds', 'update',
'traceback', 'warnings', 'wformat', and 'width'.

Option name 'lines' is a synonym for 'height' for compatibility with
previous versions.

Options 'history' and 'savehistry' (note spelling) are also available
(see gethistory() and gethistory()).

On windowed versions, option 'scrollback' is also legal.

In the Windows version, option 'keyboard' is also legal.

On Mac OS 9, options 'font' and 'fontsize' are also legal.

See topic 'options' for details on these options.

@@@@badoptok_keyword#Keyword 'badoptok'
setoptions(keyword:value [,keyword:value, ...] , badoptok:T) does the
same, except it is not an error is a non-existent or otherwise improper
option is specified.  This feature is intended to provide backward
compatibility to macros making use of new options.

@@@@structure_argument#Structure argument
setoptions(Options [,badoptok:T]), where Options is a structure with
component names matching any or all of the legal option names, sets the
options from the component values.  For example, if Options was created
by 'Options <- getoptions()', setoptions(Options) resets the options to
what they were at the time getoptions() was invoked.  See also
getoptions().

@@@@setting_default_values#Restoring default values for all options
setoptions(defaults:T) restores all the options to their default values.
It is an error if there is more than one argument.  If a prompt was set
at start up, it is restored.  When setoptions(defaults:T) occurs in a
batch file, the current batch prompt is restored to what it was when the
batch file was opened, either the file name or the value of keyword
'prompt' on the batch() command.  See batch().

@@@@options_menu_on_macintosh#Options menu on Mac OS 9
On Mac OS 9, you can use the Options menu to change most of the
options.  This works by generating and executing an appropriate
setoptions() command.
@@@@______

====setseeds()#random numbers
%%%%
setseeds(seed1,seed2) or setseeds(vector(seed1,seed2)), seed1 and seed2
  non-negative integers <= 2147483399
%%%%
@@@@usage#Usage
setseeds(seed1,seed2) initializes the random number generator used by
runi(), rnorm(), rbin() and rpoi().  The seeds should be non-negative
integers <= 2147483399.

setseeds(seeds), where seeds is a vector of the form vector(seed1,
seed2), is equivalent to setseeds(seed1, seed2).  In particular, any
time after setting seeds by seeds <- getseeds(), setseeds(seeds)
restarts the generator to the state it was when you used getseeds().

If either seed is zero, the seeds are intialized with values generated
from the time of day; the seeds generated will normally be printed.  You
can suppress the printing by setseeds(0,0,quiet:T).

@@@@see_also#Cross references
See also topics getseeds(), runi(), rnorm(), rpoi(), rbin() and
subtopic 'options:"seeds"'.
@@@@______

====shapeof()#variables
%%%%
shapeNames <- shapeof(arg1 [, arg2 ...] [,strict:T]), arg1, arg2, ...
  arbitrary variables, including macros and built-in functions.
%%%%
@@@@usage#Usage
shapename <- shapeof(arg), where arg is REAL, LOGICAL, CHARACTER or
LONG,  sets shapename to one of "SCALAR", "VECTOR", "MATRIX", or
"ARRAY", classifying the shape by the first of isscalar(arg),
isvector(arg), ismatrix(arg) or isarray(arg) to be true.

When arg is not REAL, LOGICAL, CHARACTER, or LONG, shapeof(arg) returns
one of "STRUCTURE", "MACRO", "FUNCTION", "GRAPH", "UNDEFINED" or "NULL"
just as does typeof(arg).

shapename <- shapeof(arg, strict:T) does the same, except "SCALAR" and
"VECTOR" are returned only when ndims(arg) = 1 and "MATRIX" is returned
only when ndims(arg) = 2.

shapenames <- shapeof(arg1, arg2 ... [,strict:T]), where arg1, arg2,
... are any variables, makes shapenames a CHARACTER vector with
length(shapenames) = number of arguments, with shapenames[i] the name of
the shape of argument i.

@@@@examples#Examples
Examples:

  Cmd> a <- sqrt(2); shapeof(a)
  (1) "SCALAR"

  Cmd> b <- matrix(run(4),4); shapeof(b)
  (1) "VECTOR"

  Cmd> shapeof(b,strict:T)
  (1) "MATRIX"

  Cmd> shapeof(run(4)) == shapeof(b) # compare shapes
  (1) T

  Cmd> shapeof(run(4),strict:T) == shapeof(b,strict:T) # compare shapes
  (1) F

  Cmd> shapeof(array(PI,1,1,1),help,NULL,T,cos,strict:T)
  (1) "ARRAY"
  (2) "MACRO"
  (3) "NULL"
  (4) "SCALAR"
  (5) "FUNCTION"

@@@@see_also#Cross references
See also topics nameof(), typeof(), isarray(), ischar(), isdefined(),
isfactor(), isfunction(), isgraph(), islogic(), ismacro(), ismatrix(),
isname(), isnull(), isnumber(), isreal(), isscalar(), isvector().

====shell()#control,general
%%%%
shell(command), shell(command,keep:T) or shell(command,interact:T),
  command a quoted string or CHARACTER scalar.
!command immediately after the prompt
%%%%
@@@@usage#Usage
shell(command) submits the CHARACTER vector or string command to the
operating system for execution.  It is implemented in the Unix/Linux,
Motif, and DOS versions but not on the Macintosh.  It does not work in
Windows 3.1 or Windows 95 but may in Windows NT.  Except in the limited
memory DOS version (BCPP), the program run by command must not expect
any input from the keyboard.

For example, in the Unix/Linux or Motif versions,
  Cmd> shell("ls -l *.dat")
causes the output from the Unix/Linux command 'ls -l *.dat' to be
printed, giving a full listing of all files in the current directory
with names ending with '.dat'.  Under DOS, the same effect is obtained
by
  Cmd> shell("dir *.dat").

@@@@interact_keyword#Keyword 'interact'
shell(command, interact:T) does the same as shell(command) except that
you can interact with the program that is started up.  This option is
required if, for example, you are using shell() to run an editor to
modify a file.  In the limited memory DOS version (BCPP), you can always
interact with the command.  When in doubt as to whether a program
expects keyboard input, use interact:T.

@@@@keep_keyword#Keyword 'keep'
shell(command, keep:T) runs the command in non-interactive mode and
returns its output as a CHARACTER vector, with each line of output an
element.  The command must not expect any input from the keyboard.  This
is not implemented in the limited memory DOS version (BCPP).

@@@@example_on_unix#Example on Unix/Linux
  Cmd> datafiles <-\
        shell(paste("cd ",DATAPATHS[1],"; ls *.dat"), keep:T)
returns a vector of file names of the form *.dat in the directory whose
name is in DATAPATHS[1].  See topic 'DATAPATHS'.

@@@@operating_system_escapes
                        Operating System Escapes
Somewhat simpler, but less powerful because it cannot be included in a
macro, is the use of the 'escape' character '!'.  In the Unix/Linux,
Motif and DOS versions, any line of input starting with '!' immediately
after the prompt will be passed on to the operating system for execution
(without the '!').  Specifically,
  Cmd> !command to be run ...
is equivalent to
  Cmd> shell("command to be run ...", interact:T).
For example,
  Cmd> !ls -l *.dat
and
  Cmd> shell("ls -l *.dat", interact:T)
are equivalent.

In a command line starting with '!', double quotes ('"') and curly
brackets ('{' and '}') have no special significance.  The only "special"
character is a backslash ('\') and then only when it occurs at the end
of line to indicate that the command is continued on the next line.
Unlike the case when an ordinary line is continued with backslash, a
trailing backslash is deleted and is not seen by the operating system.
Unbalanced quotes or brackets are ignored.

Under DOS, but not Unix/Linux, you can change default directories by,
for example,
  Cmd> !cd b:\data   # or shell("cd b:\\data")

@@@@caution
Caution: If you want to execute in MacAnova a command that starts with
'!'  (for example !(x < y)), precede it with a space.  For example,
  Cmd> !(x < y)
attempts to execute "(x < y)" as a shell command, probably causing an
error, while
  Cmd>  !(x < y) #note the extra space
is computed in MacAnova.  Conversely,
  Cmd>  !ls -l *.dat
is an error, because a space has been typed before '!'.

@@@@comparison_of_versions#Comparison of versions
In the DOS extended memory version (DJGPP), shell(command) or
shell(command, keep:T) sometimes hangs.  shell(command,interact:T) or
!command is more reliable.

In the Windows version, shell(command,interact:T) and !command ignores
command and starts up DOS similar to selecting MS-DOS Prompt in the
Program Manager window.

In the Motif version, shell(command,interact:T) and !command can be
confusing: Output does not appear in the MacAnova command window, but in
the "parent" window from which MacAnova was started up, and any input
must be typed in parent window.

On a Macintosh, starting a line with '!' is an error.
@@@@______

====showplot()#plotting
%%%%
showplot([Graph] [,graphics keyword phrases])
%%%%
@@@@usage#Usage
showplot(Graph) redraws the graph whose information is encapulated in
Graph, which must be a variable of type GRAPH.  If Graph is omitted,
GRAPH variable LASTPLOT is plotted instead.

If option 'dumbplot' has been set False (see subtopic
'options:"dumbplot"'), the plot will be a low resolution plot unless
'dumb:F' is an argument.

@@@@graphics_keywords#Graphics keywords
Keywords 'dumb', 'xmin', 'xmax', 'ymin', 'ymax', 'logx', 'logy', 'xlab',
'ylab', 'title', 'xaxis', 'yaxis', 'borders', 'ticks', 'xticks',
'yticks', 'xticklen', 'yticklen', 'xticklabs', 'yticklabs', 'height',
'width', 'pause', 'silent' and 'notes' may be used as for other plotting
commands.  See topics 'graph_keys', 'graph_border' and 'graph_keys'.
This allows you to change the original labeling and limits, as well as
modify tick mark placement and labelling and which borders of the plot
are drawn.

@@@@updating_LASTPLOT#Updating LASTPLOT
As all plotting commands, showplot() updates LASTPLOT to reflect the
graph being plotted.  To suppress the creation or updating of LASTPLOT,
use keyword phrase 'keep:F' as an argument.  Occasionally when memory is
limited, it may be necessary to use keep:F to view the graph.

See topic 'graph_assign' for information on another way to make plots.

See also plot(), chplot(), lineplot().

====sin()#transformations
%%%%
sin(x [, degrees:T or radians:T or cycles:T]), x REAL or a structure
  with REAL components x in radians (default), cycles, or degrees as set
  by option "angles" or the optional keyword.
%%%%
@@@@usage#Usage
sin(x) computes the sines of the elements of x, where x is a REAL
scalar, vector, matrix or array.  The result has the same shape as x.

The argument is considered to be in units of radians, degrees or cycles
as determined by the value of option 'angles'.  The default is radians.
See subtopic 'options:"angles"'.

sin(x, radians:T), sin(x, degrees:T), sin(x, cycles:T) interpret x as in
the indicated units, regardless of the value of option 'angles'.

If any element of x is MISSING or is too large (> 5000000*PI radians in
absolute value), the corresponding element of the result is MISSING and
a warning message is printed.

@@@@structure_argument#Structure argument
When x is a structure, all of whose non-structure components are REAL,
sin(x [,UNITS:T]), where UNITS is one of 'radians', 'degrees' or
'cycles', is a structure of the same shape and with the same component
names as x with each non-structure component transformed by sin().

@@@@see_also#Cross references
See topic 'transformations' for more information on sin(), including its
use with a CHARACTER argument.
@@@@______

====sinh()#transformations
%%%%
sinh(x), x REAL or a structure with REAL components
%%%%
@@@@usage#Usage
sinh(x) returns the hyperbolic sine of the elements of x, when x is a
REAL scalar, vector, matrix or array.  The result has the same shape as
x.  In terms of other functions, sinh(x) = (exp(x) - exp(-x))/2.

If any element of x is MISSING or > 710.4758600739439 in absolute value,
the corresponding element of sinh(x) is MISSING and a warning message is
printed.

When x is a structure, all of whose non-structure components are REAL,
sinh(x) is a structure of the same shape and with the same component
names as x, with each non-structure component transformed by sinh().

@@@@see_also#Cross references
See topic 'transformations' for more information on sinh().
@@@@______

====solve()#linear algebra
%%%%
solve(A [,singok:T] [,quiet:T]), square REAL matrix A
solve(A, B [,singok:T] [,quiet:T]), square REAL matrix A, REAL matrix B,
  with nrows(B) = nrows(A).
%%%%
@@@@usage#Usage
solve(a) computes the inverse of the square matrix a.

solve(a,b) computes the solution x to the linear equation a x = b, where
a is square and b is a REAL vector or matrix with the same number of
rows as a.  solve(a,b) is mathematically, but not computationally, the
same as solve(a) %*% b.

For either usage, if a is singular, an informative message is printed
and the operation aborts.

MISSING values are not allowed in a or b.

Expression a %\% b is equivalent to solve(a, b).

@@@@singok_keyword#Keyword 'singok'
solve(a, singok:T) and solve(a, b, singok:T) does the same, except when
a is singular, no message is printed and NULL is returned.  This allows,
for example, a macro to test whether a matrix is singular and take
corrective action.

@@@@quiet_keyword#Keyword 'quiet'
Occasionally, "overflow" occurs during the computation.  Any values in
the result that are too large to be represented are replaced by MISSING
and a WARNING message is printed.  You can suppress the message by
including 'quiet:T' as an argument.  If you do, you should use
anymissing() to check the result for the presence of MISSING elements.

@@@@propagation_of_labels#Propagation of labels
If a has labels, the row and column labels of solve(a) are the column
and row labels of a, respectively.  If b is compatible, the row and
column labels of solve(a,b) are the column labels of a and b
respectively.  If b does not have labels, the column labels of
solve(a,b) are rep("a", ncols(b).  See topic 'labels'.

@@@@see_also#Cross references
See also topics rsolve(), swp(), qr(), 'matrices'.
@@@@______

====sort()#ordering
%%%%
sort(x [ ,down:T]), x REAL or CHARACTER or a structure with all REAL
  or all CHARACTER components.
%%%%
@@@@usage#Usage
sort(x) sorts the data in a REAL or CHARACTER vector x into ascending
order.

sort(x, down:T) or simply sort(x,T) sorts the data in descending order.

If x is a matrix, sort(x) or sort(x,T) is a matrix each of whose columns
contains the ordered elements of the corresponding column of x.

If x is an array, sort(x) or sort(x,T) is an array of the same size and
shape with all the elements with fixed values of subscripts 2, 3,
... defining a "column" which is sorted.  An array with dimension > 2 is
always treated as an array and not as a matrix, even if there are at
most two dimensions greater than 1.

With REAL data, any MISSING values in a column are sorted to the end of
the column, regardless of the direction of the sort.

@@@@sorting_character_data#Sorting character data
With CHARACTER data, elements are sorted using the ASCII collating
sequence in which most punctuation and all numerals sort ahead of upper
case letters which sort ahead of lower case letters.  A space sorts
ahead of all printable characters.  Here is the explicit ordering
starting with space:
    !"#$%&'()*+,-./0123456789:;<=>?
   @ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_
   `abcdefghijklmnopqrstuvwxyz{|}~

@@@@structure_argument#Structure argument
It is also acceptable for x to be a structure, whose non-structure
components are all REAL or all CHARACTER.  In that case, sort() returns
a structure of the same form, each of whose non-structure components is
the result of applying sort() to the corresponding component of x.

@@@@see_also#Cross references
See also grade(), rank().
@@@@______

====split()#combining variables,structures
%%%%
split(x,A [,compnames:CharVar ,silent:T]), x REAL, A a factor or vector
  of integers or LOGICAL vector, CharVar a CHARACTER scalar or vector
split(x,bycols:T or byrows:T [,compnames:CharVar, silent:T]), x a REAL
  matrix
%%%%
@@@@usage#Usage
split(Data,Factor) creates a structure by splitting Data along its first
subscript into separate components according to the values of Factor all
of whose elements must be positive integers.

If N = max(Factor), the result has N components, some of which may be
empty.  Thus, when the values in Factor are group or treatment numbers,
each component of the result consists of the data corresponding to a
particular group or treatment.  It is an error if N > 32767.

It is also acceptable for Factor to be a LOGICAL vector, in which case
False and True correspond to factor levels 1 and 2, respectively.  For
example, split(y, x <= 0) would create a structure with two components.

Data must be REAL or LOGICAL and the components of the result are the
same type.  Each component of the result will be a vector, matrix or
array, depending on whether Data is a vector, matrix, or array.  A
warning is printed if any component of the result contains no elements.
If Factor[i] is MISSING, all the corresponding data are omitted.  It is
an error for all the elements of Factor to be MISSING.

split(Data,Factor,silent:T) does the same, except warning messages about
missing values in Factor or empty components in the result are
suppressed.

@@@@names_of_components#Names of components
If Factor is a variable rather than an expression, say groups or
@groups, the components will be named 'groups1', 'groups2', etc.
Similarly if Factor is specified in a keyword phrase such as
dose:rep(run(4),5), components will be named 'dose1', 'dose2', etc.

@@@@bycols_and_byrows_keywords#Keywords 'bycols' and 'byrows'
split(Data,bycols:T) or simply split(Data) splits the data along the
last subscript, creating a structure with one component corresponding to
each value of the last subscript.  The most important case is when Data
is a m by n matrix, in which case the result each of the n components of
the result is a vector containing the data from a column of Data.
Components will be named 'col1', 'col2', ... .  If Data is a vector, the
result is a structure with a single component named 'col1'.

split(Data,byrows:T) splits the data along the first subscript, creating
a structure with one component corresponding to each value of the first
subscript.  For example, when Data is a m by n matrix, the result is a
structure with m components, each a row vector of size n (1 by n
matrix).  Components will be named 'row1', 'row2', ... .

@@@@compnames_keyword#Keyword 'compnames'
For all these usages, an additional argument of the form
compnames:CharVec, is recognized, where CharVec is a CHARACTER vector.
The elements of CharVec are used as names for the components of the
result, truncated to 12 characters if necessary, overriding the naming
conventions just described.  If length(CharVec) = 1, say "group", it is
used as a "root" for forming names for the components of the form
"group1", "group2", ... .  Otherwise length(CharVec) must match the
number of components of the result.  It is an error if any element of
CharVec contains '$'.

@@@@use_with_boxplot#Use with boxplot()
An important use of split is in boxplot(split(y,groups)), where y is a
REAL vector and groups is a factor.  This produces parallel boxplots of
the of the data in y corresponding to each level of groups.  Similarly,
when y is a REAL matrix, boxplot(split(y,bycols:T)) or simply
boxplot(split(y)), produces parallel box plots of the data in each
column of y.

@@@@examples#Examples
Examples:
  Cmd> split(run(4),variety:vector(1,2,1,2))
  component: variety1
  (1)            1            3
  component: variety2
  (1)            2            4

An equivalent command would be
  Cmd> split(run(4),vector(1,2,1,2),compnames:"variety")

  Cmd> boxplot(split(y),ylab:"Column Number")
where y is a matrix, produces parallel boxplots of the columns of y.

@@@@see_also#Cross references
See also topics boxplot(), 'structures'.
@@@@______

====spool()#output,files
%%%%
spool(FileName [,new:T] [,everything:T or F])
spool() toggles spooling on and off.
spool(,new:T) restarts spooling on the same file
spool(,everything:T or F)
%%%%
@@@@usage#Usage
spool(FileName) begins printing MacAnova input and output into the file
with name given in the CHARACTER variable FileName.  If the named file
already exists, the spooled output will be added at the end of the file,
thus allowing a cumulative record of several runs.  Comments to annotate
what you have done may be added to input lines by preceding them with
'#'.  See topic 'comments'.  In a version with windows, when FileName
is "", you will be prompted for a name.

Output to the screen or window that is suppressed because option 'quiet'
has been set True, is not spooled to the file either.

spool() suspends spooling if spooling is currently in effect and
restarts it on the same file if spooling was previously in effect but is
not now.

spool(FileName, new:T) restarts spooling at the beginning of the spool
file, destroying any lines previously spooled.

spool(, new:T) restarts or resumes spooling at the beginning of the most
recently used spool file, destroying any lines previously spooled.

@@@@keyword_everything#Keyword 'everything'
spool(FileName, everything:T [,new:T]) does the same, except lines are
spooled even when output to the screen or window is suppressed by option
'quiet'.

spool(, everything:T or F) allows or suppresses spooling of lines
suppressed by setoptions(quiet:T).  It does not turn toggle spooling on
or off.

@@@@menu_selection#Menu selection
On a Mac OS 9, selecting item Spool Output to File on the File menu is
equivalent to typing 'spool("")'.  If a spool file name has previously
been provided, the item is labeled either Suspend Spooling or Resume
Spooling and is equivalent to 'spool()'.  In both cases it first erases
everything after the prompt.
@@@@______

====sqrt()#transformations
%%%%
sqrt(x), x REAL or a structure with REAL components
%%%%
@@@@usage#Usage
sqrt(x) returns the square roots of the elements of x, when x is a
REAL scalar, vector, matrix or array.  The result has the same shape as
x.

If any element of x is MISSING, so is the corresponding element of
sqrt(x).  If any element of x < 0, the corresonding element of sqrt(x)
is MISSING.  In both cases a warning message is printed.

When x is a structure, all of whose non-structure components are REAL,
sqrt(x) is a structure of the same shape and with the same component
names as x, with each non-structure component transformed by sqrt().

@@@@see_also#Cross references
See topic 'transformations' for more information on sqrt().
@@@@______

====stemleaf()#descriptive statistics,plotting
%%%%
stemleaf(x [, nstems, outliers:F, depth:F, stats:T,\
   title:"Your title"]), x a REAL vector
%%%%
@@@@usage#Usage
stemleaf(var) prints a stem and leaf display of the data in REAL vector
var.  The number of stems depends on the number of non-missing values
(must be at least 2) and the number of lines on the screen, and the
maximum number of leaves printed is determined by the screen width (see
subtopic 'options:"width"').  An asterisk as the last leaf on a stem
indicates there has been truncation and some leaves have not been
printed.

stemleaf(nvar,nstems), nstems an integer > 1, selects the number of
stems to be as large as possible <= nstems.

The data are scaled by a power of 10 and rounded toward zero so as to be
integers.  Then the final digits are the leaves and the stems are the
leftmost digits or 0.  If two stems go with a value, they are labeled,
for example, as '2*' and '2.'), If 5 stems go on a value, they are
labeled, for example, as '2*', '2t', '2f', '2s', and '2.'.  A final line
specifies the unit of the leaf digit.

By default, outliers more than 1.5 IQR beyond the lower or upper
quartiles are listed separately and are not put on a stem, where IQR is
the inter-quartile range.

@@@@depth_column#Depth column
By default, a "depth" column accumulating counts from each end is
printed.  The depth for the stem that contains the median is the number
of leaves on that stem enclosed in parenthese.

@@@@keywords#Keywords
With both forms additional keyword arguments are as follows:
   outliers:F         This suppresses the special treatment of outliers;
                      all values are put on stems
   depth:F            Suppresses printing the "depth" column.
   stats:T            Print the sample size, extremes and quartiles.
   title:"Your title" Prints the specified CHARACTER variable before
                      display

@@@@see_also#Cross references
See also boxplot().
@@@@______

====strconcat()#structures,combining variables
%%%%
strconcat(var1 [,var2,...,vark] [, KeyPhrases]), where var1, var2, ...
  are arbitrary variables
KeyPhrases can be compnames:Names, labels:Labels, notes:Notes and
  silent:T, where Names, Notes and Labels are CHARACTER scalars or
  vectors.  Arguments var1, ... can also be keyword phrases with keyword
  names other than 'compnames', 'labels', 'notes' and 'silent'.
%%%%
@@@@usage#Usage
strconcat(a,b,c,...) creates a structure from variables or structures a,
b, c, ... .

strconcat() differs from structure() in that, when an argument is a
structure, its top level components become top level components of the
result, while a structure argument to structure() becomes a single
component of the result.  For example, suppose a and d are non-structure
variables.  Then the value of strconcat(a, structure(b,c),d) is a
structure with 4 components, a, b, c, and d, while the value of
structure(a, structure(b,c),d) is a structure with 3 components, the
second of which is itself a structure with 2 components.

The names of components derived from non-structure arguments are
determined similarly to the names of components of structures created by
structure(), except that when varj is a keyword phrase, the keyword name
is ignored when the argument is a structure.

@@@@attaching_labels_or_notes#Attaching labels or notes
You can attach a vector of labels to a structure Str, one element for
each top level component, by Str <- strconcat(Str, labels:CharVec),
where CharVec is either a CHARACTER scalar or a CHARACTER vector of
length ncomps(Str).  When the structure is printed, the labels are used
instead of the component names.  You remove labels by Str <-
strconcat(Str,labels:NULL).  See topic 'labels' for more information.

str <- strconcat(a,b,...,notes:Notes), where Notes is a CHARACTER scalar
or vector, attaches Notes to str.  See topic 'notes'

When there is just one nonkeyword argument and it is a structure, its
labels or notes, if any, are transferred to the output unless keywords
'labels' and/or 'notes' are arguments.

@@@@other_keywords#Other keywords
See structure() for information about keywords 'compnames', 'notes' and
'silent'.

@@@@example#Example
Example: Build structure in a loop
  Cmd> nterms <- dim(SS)[1];f <- structure(SS[1]/DF[1])
  Cmd> for(i,2,nterms-1){f <- strconcat(f,SS[i]/DF[i]);;}
  Cmd> f <- strconcat(f/(SS[nterms]/DF[nterms]),\
        compnames:TERMNAMES[-nterms])
This produces a structure consisting of F-statistics with components
having the names of the terms.

@@@@see_also#Cross references
See also topics 'structures', structure(), compnames(), changestr(),
'keywords'.
@@@@______

====stringplot()#plotting
%%%%
stringplot([Graph,] x,y, strings:charVec,[, add:T, graphics keyword
  phrases])
stringplot([Graph,] [x,y, strings:charVec],keys:str), str a structure
  whose component names are graphics keywords
%%%%
@@@@usage#Usage
stringplot(x,y,strings:charVec) draws a graph, drawing charVec[i] at
position (x[i], y[i]).  x and y must be REAL vectors and charVec a
CHARACTER vector, all of the same length.  This contrasts with the
behavior of other plotting functions (except addstrings()) which allow y
to be a matrix, and permit x to be a scalar or vector of length 2 coding
equally spaced values.

It is not an error when x or y is NULL; a warning message is printed and
no plotting occurs.

For backward compatibility with earlier versions, keyword 'strings' can
be omitted (stringplot(x,y,charVec)).

If option 'dumbplot' has been set False (see subtopic
'options:"dumbplot"'), the plot will be a low resolution plot unless
'dumb:F' is an argument.

@@@@justifying_strings#Justifying strings
By default, each string is written centered at (x[i], y[i]).  However,
if 'justify:"l"' or 'justify:"r"' is an argument following charVec, each
string will be left or right justified.

@@@@graphics_keywords#Graphics keywords
Most of the usual graphics keywords may be used, including 'xmin',
'xmax', 'ymin', 'ymax', 'logx', 'logy', 'xlab', 'ylab', 'title',
'border' and keywords related to ticks, but not 'symbols', 'lines',
'linetype', 'thickness' or 'impulses'.  See topic 'graph_keys'.

In particular, stringplot() is most commonly used with add:T, in which
case the strings being drawn are added to the graph encapsulated in
GRAPH variable LASTPLOT.  With 'add:T', stringplot() is equivalent to
addstrings().

@@@@graph_variable_argument#Graph variable argument
stringplot(Graph,x,y,strings:charVec), displays GRAPH variable Graph,
adding the string or strings in charVec, and saves the modified plot in
LASTPLOT.  Graph is not changed (unless it is LASTPLOT).

@@@@examples#Examples
The most usual use is when both x and y are REAL scalars and charVec is
a quoted string or CHARACTER scalar to be added to a plot at coordinates
(x,y).  A typical usage would be
  Cmd> stringplot(110,20,strings:"Frequency 1 cycle/week",\
    justify:"l",add:T)

Alternatively you can use addstrings():
  Cmd> addstrings(110,20,strings:"Frequency 1 cycle/week", justify:"l")

@@@@keep_and_show_keywords#Keywords 'keep' and 'show'
stringplot(x,y,strings:charVec,keep:F) suppresses any change to
LASTPLOT.

stringplot(x,y,strings:charVec,show:F,add:T) suppresses immediate
display of the modified graph but updates LASTPLOT.  This is useful when
you are building a complex graph in stages using addlines(), addchars(),
addpoints(), or stringplot().  When you are done, simply type
showplot().  You can't use both show:F and keep:F.

@@@@keys_keyword#Keyword 'keys'
stringplot([Graph,] keys:structure(x:x,y:y,strings:charVec [other
keyword phrases])) is equivalent to stringplot([Graph,] x:x,y:y,
strings:charVec [other keyword phrases]).  See topic 'graph_keys' for
details.

@@@@see_also#Cross references
See topic 'graph_assign' for information on another way to make plots.

See topic 'graphs' for general information on plots and on variable
LASTPLOT.  See topic 'graph_keys' for information on keywords.  See
topic 'graph_files' for information on writing a graph to a file.
@@@@______

====structure()#structures,combining variables
%%%%
structure(var1 [,var2,...,vark] [, KeyPhrases]), where var1, var2, ...
  are arbitrary variables
KeyPhrases can be compnames:Name, labels:Labels, notes:Notes and
  silent:T, where Names, Notes, and Labels are CHARACTER scalars or
  vectors.  Arguments var1, ... can also be keyword phrases with keyword
  names other than 'compnames', 'labels', 'notes' and 'silent'.
%%%%
@@@@usage#Usage
structure(var1,var2,....,vark) creates a structure with components named
var1, var2, ..., vark.  The values of the components are equal to var1,
etc.

structure() differs from strconcat() in that the any argument that is a
structure becomes a single component in the result, whereas strconcat()
splits it into its top level components, each of which become top level
components of the result.

@@@@names_of_components#Names of components
When varj is a keyword phrase of the form name:value, the component is
named from the keyword.  For example, when a, b, and c are variables,
structure(a,b,c) and structure(a:a,b:b,c:c) are equivalent.  The names
should differ from the keyword names 'labels', 'notes', 'silent'
and 'compnames' recognized by structure().  See below for a work around.

When varj is a temporary variable, that is, a variable whose name starts
with '@', then the '@' is stripped off to create the name of the
component.  For example, when @x is defined, structure(@x,...) is the
same as structure(x:@x,...).

If varj is an expression or function result, for example "3+4" or "x'",
the component name will be NUMBER, LOGICAL, STRING, VECTOR, MATRIX,
ARRAY, STRUCTURE, MACRO, or GRAPH depending on the type and shape of the
component.

structure(var1, var2, ..., compnames:Names), where Names is a CHARACTER
vector or scalar, forms component names from Names, whose elements are
truncated to 12 characters, if necessary.  These take precedence over
other names as described above.  If Names is a scalar, say "Comp", it is
used as a root to create names of the form "Comp1", "Comp2", ... .
Otherwise the number of elements in Names must match the number of
components in the output.  This usage is particularly useful in
assigning names of 11 or 12 characters such as 'covariances" or
'factorloding'.

@@@@legal_component_names#Legal component names
It is an error if any element of Names contains '$', a space or other
"invisible" character.

@@@@attaching_labels_or_notes#Attaching labels or notes
structure(var1, var2, ..., labels:Labels), where Labels is a CHARACTER
vector or scalar, labels the components using Labels.  If Labels is a
vector, then its length must match the number of components.  The labels
are printed instead of the component names on all output.  See topic
'labels'.  See strconcat() for information on how to add or remove
labels from an existing structure.

structure(var1, var2, ..., notes:Notes), where Notes is a CHARACTER
scalar or vector, attaches Notes as descriptive notes to the result.
See topic 'notes'.

@@@@silent_keyword#Keyword 'silent'
You can suppress all warning messages by silent:T as in structure(x, y,
labels:vector("Height","Strength"), silent:T).

@@@@order_of_arguments#Order of arguments
Keywords compnames, labels, notes, and silent must follow all arguments
that are to be included in the output structure.  If you want a
component with one of these names, either name it using keyword
'compnames' or make sure it is not the last component in the result.
For example, to have a component 'labels', use, say, structure(1,"A",
compnames:vector("x","labels")) or structure(labels:"A", x:1).

@@@@examples#Examples
Example: You can create a structure with components min and max by
  Cmd> extremes <- structure(min:min(x), max:max(x))
by
  Cmd> @min <- min(x);@max <- max(x); extremes <- structure(@min,@max)
or by
  Cmd> extremes <- structure(min(x),max(x),\
        compnames:vector("min","max"))

In all three cases, to give a more complete labeling of the components
you can include an argument like labels:vector("Minimum of x", "Maximum
of x") .

@@@@see_also#Cross references
See also topics strconcat() and 'structures'.
@@@@______

====structures#structures,syntax,variables
%%%%
Create a structure:
  Str <- structure(Name1:x,Name2:y,...[, compnames:Name])
  Str <- strconcat(Name1:x,Name2:y,...[, compnames:Name])
Extract components of a structure:
  Str$name  or  Str[J]  or  Str[[J]]
Number of components of a structure:
  ncomps(Str)
Component names of a structure:
  compnames(Str)
Test whether variable is a structure:
  isstruc(x)
Modify a structure:
  Str[J] <- x or Str[[J]] <- x, legal subscript vector J
  Str[[i]][[J]] <- x, integer scalar i, legal subscript vector J
  Str$a <- x, Str$a$b <- x, ...
  Str <- changestr(Str,"compname",x), equiv. to Str$compname <- x
  Str <- changestr(Str,compname:x), same as preceding
  Str <- changestr(Str,n,x), positive integer n <= ncomps(Str)+1
  Str <- changestr(Str,-n), equivalent to Str <- Str[-n]
%%%%
@@@@description_of_structure#Description of structure
A 'structure' is made up of one or more named components, each of which
may itself be a variable or another structure.

A single component can be extracted by name using a '$'.  For example,
if Stats is structure(mean:xbar, var:s_sq), then xbar <- Stats$mean and
s_sq <- Stats$var set xbar and s_sq to the values of components 'mean'
and 'var', respectively.

When a component of a structure is itself a structure, you can use a
chain of component names.  For example, if structure Str has component
'a' which is a structure with component 'b', Str$a$b accesses that
component.  If Str$a$b is itself a structure with component 'c',
Str$a$b$c accesses that component

@@@@creating_a_structure#Creating a structure
Some functions and macros, for example secoefs(), describe() and
eigen(), return structures as their values.

You can use structure() and strconcat() to create a structure with
specified components.

You can use strconcat() to combine the components in two or more
structures into one larger structure, optionally including additional
variables as comnponents.

You can use split(y, f), where y is a vector or matrix and f is a
factor, to create a structure whose j-th component consists of the rows
of y associated with level j of f.  split(y) returns a structure, each
of whose components is a column of y.  split(y,byrows:T) returns a
structure, each of whose components is a row of y.  See split().

You can use changestr() to delete components from, replace components
in, or add new components to an existing structure.  See structure(),
strconcat() and changestr().  You can also modify an existing structure
by assigning a variable to one or more components selected by a
subscript.  See below.

vector(Str) "unpacks" a structure Str, returning all the elements in its
non-structure components as a vector.  All the non-structure components
must be of the same type, REAL, CHARACTER or LOGICAL.

@@@@functions_used_with_structures#Functions used with structures
ncomps(Str) returns the number of (top level) components in structure
Str.  See also ncomps().

compnames(Str) returns a CHARACTER vector of the names of the (top
level) components in structure Str.  See also compnames().

isstruc(x) returns True when x is a structure.  More generally,
isstruc(x1, x2, ...) returns a LOGICAL vector whose elements are True or
False depending on whether the corresponding argument is a structure.

equal(str1, str2) compares two structures, returning True only when all
their components and subcomponents are equal.  See equal().

@@@@assignment_to_components#Assignment to components
Str[J] <- x, where J is a legal vector of subscripts and x is a
variable, often a structure with ncomps(x) = number of components
selected by J, replaces elements of an existing structure Str.  See
topics 'subscripts' and 'assignment'.

@@@@structure_arguments_to_functions#Structure arguments to functions
Many functions accept structures as arguments, including describe(),
sum(), prod(), max(), and min(), and all the transformations.  Each
component of the result is obtained as the function of the corresponding
component argument.  For example, sum(structure(x,y)) is the same as
structure(x:sum(x),y:sum(y)).

@@@@binary_and_unary_operators_with_structures#Binary and unary operators with structures
Both binary (for example, +, *, %*%) and unary (-, +, !)  operators
accept structures as operands.  Most of these produce a structure of the
same shape as the argument(s) or operands(s).  For example,
structure(a1,a2) %*% structure(b1,b2) = structure(a1 %*% b1,a2 %*% b2).

In addition, if one operand of a binary operation is a structure and the
other is not, the result is a structure, each of whose components is
computed by combining a component of the structure argument with the
other argument.  For example, 3*structure(a,b,c) is the same as
structure(a:3*a,b:3*b, c:3*c), and structure(a,b) %C% c, is the same as
structure(a:a %C% c,b:b %C% c).

Note: You cannot use a structure as an operand to %/% or %\%.  See
topic 'matrices'.

@@@@extracting_components#Extracting components
You can extract components of structure Str using subscripts instead of
a name.  For example, if Stats is structure(mean:xbar, var:s_sq),
'Stats[1]' and 'Stats[2]' are equivalent to 'Stats$mean' and
'Stats$var', respectively.

If there are more than one component with the same name or if the
structure name is not a legal variable name, this is the only way to
extract the component.  For example Str <- structure(dim(x)[1],
dim(x)[2], sqrt(x)) creates a structure with three components, named
NUMBER, NUMBER, and MATRIX, but Str$NUMBER retrieves only the first
component and Str[2] must be used to retrieve the second.

Usually it is preferable to name components using keywords.  For
example, Str <- structure(m:dim(x)[1],n:dim(x)[2],data:sqrt(x)) creates
a structure with components named 'm', 'n', and 'data'.  You can also
name components using keyword 'compnames' on structure(), strconcat()
and split().

Str[NULL] is NULL.  See topic 'NULL'.

More generally, in an expression of the form Str[J], J may be a vector
of positive integers, a vector of distinct negative integers, or a
LOGICAL vector of length ncomps(Str).  Str[J] is a structure whose
components are the components of Str selected by J in the same way
elements of a vector vec would be extracted by vec[J].  If J selects
only one component, Str[J] is that component.  If J selects no
commponents (all F's or a full set of negative values), STR[J] is NULL.
See topic 'subscripts' for how such a vector of subscripts is
interpreted.

@@@@alternative_subscript_form#Alternative subscript form
An alternative way to extract components from a structure is Str[[J]],
using double square brackets.  This is equivalent to Str[J] when Str is
a structure.  However, when x is not a structure, the value of x[[1]] is
x, not x[1], and, if J != 1, x[[J]] is an error.  This feature can be
useful in a macro when an argument can either be a non-structure
variable or the first component of a structure.

Examples: When Stats is structure(mean:xbar, var:s_sq),
Stats[vector(2,1)] is equivalent to structure(var:Stats[2],
mean:Stats[1]), and Stats[vector(F,T)] is equivalent to Stats[2] or
Stats$var.

@@@@replacing_components#Replacing components
You can replace one or more components of a structure by assigning to
subscripts.  For example, if Stats is as above, Stats[2] <- vector(1,3)
will replace component 'var' by vector(3,10) without changing its name.
Stats[[2]] <- vector(1,3) has the same effect.

You can also change a single named component by assignment.  For
example, if Stat is as above, Stats$var <- vector(1,3) is equivalent
to stats[2] <- vector(1,3).

You can change subcomponents at any depth <= 31 by assignment.  For
example, x is structure(a:run(3),b:structure(A:1,B:2,C:3)), all of x$b$C
<- PI, x[[2]]$C <- PI, x$b[[3]] <- PI or x[[2]][[3]] <- PI are
equivalent.

See topic 'assignment' for details on assignment to structure
components.

You can use changestr() to modify a structure.  See changestr() for
details.
@@@@______

====subscripts#syntax
%%%%
Ordinary subscripts: x[13], y[2,vector(4,5)]
Negative subscripts: w[-vector(1,3,5)], z[-run(5),-1]
Logical subscripts:  a[vector(T,T,F,F)], b[b < 0]
%%%%
@@@@types_of_subscripts#Types of subscripts
Elements of vectors may be selected in several ways using a list of
integer or LOGICAL subscripts inside of square brackets.  The list must
be of one of three forms.  In the examples, z is assumed to be
vector(1,7,4,9,6).

A list of one or more positive integers.
  Examples: z[4] is 9 and z[vector(1,1,2,2,5,4)] is vector(1,1,7,7,6,9).

A list of negative subscripts. These indicate omission of the absolute
values of the subscripts.  If all subscripts are omitted the result is
NULL.  See topic 'NULL'.
  Examples: z[vector(-1, -3, -5)] is vector(7,9).
            z[-run(5)] is NULL

A LOGICAL vector with the same length as the source vector. The value is
a vector with elements corresponding to values of True.  If all the
elements are False, the result is a NULL variable, with no elements.
  Examples: z[z > 4] is z[vector(F,T,F,T,T)] = vector(7,9,6).
            z[z > 9] is z[vector(F,F,F,F,F)] = NULL

@@@@erroneous_use_of_subscripts#Erroneous use of subscripts
z[vector(1,2,?)] would be an error because MISSING values are not
allowed as subscripts.

z[vector(-3,-4,-3)] would be an error because there are duplicate
negative subscripts.

z[vector(-1,2)] would be an error because there are both positive and
negative integers in the same vector of subscripts.

@@@@use_of_subscripts_with_matrices_and_arrays#Use of subscripts with matrices and arrays
Elements of matrices may be accessed in an analogous manner to vectors,
except that both dimensions must be specified, separated by a comma.  An
empty row or column specification implies all rows or columns.  Suppose
                                    [1   4]
q is the matrix  matrix(run(6),3) = [2   5] .
                                    [3   6]

Then q[3,1] is 3, and both q[vector(1,3),2] and q[-2,2] are the column
vector 4,6 with dimensions 2 and 1.  q[3,] is the row vector 3,6 and
q[q[,1]>=2,] selects those rows of q for which column 1 is not less than
2, that is rows 2 and 3.

Elements of arrays may be accessed as for matrices, except that you must
specify all subscripts.  Again, an empty subscript specifies all legal
values for that subscript.

With vectors, matrices or arrays, if any subscript is NULL or is
non-selecting (all False or a complete set of negative subscripts), the
result is a NULL variable.

@@@@too_many_subscriupts#Too many subscriupts
It is not an error to use more subscripts than there are dimensions as
long as no extra subscript specifies an element greater than the first
for that dimension.  Extra trailing empty subscripts are ignored, so
that for example, run(5)[-1,] and run(5)[-1] are identical.  Extra
subscripts that are 1 or T have the effect of increasing the number of
dimensions.

For example, run(5)[-1,1] and run(5)[-1,T] are equivalent and result in
a 4 by 1 matrix instead of a vector of length 4, but run(5)[-1,2] is an
error.  This is a useful feature when writing macros that may operate on
vectors and matrices, or deal with both ANOVA and MANOVA SS.  For
example, SS[3,,] is equivalent to SS[3] after anova() and is also
meaningful after manova() when SS is a 3 dimensional array.

@@@@too_few_subscripts#Too few subscripts
If a is a matrix or array, and i is a vector, then a[i] is equivalent to
vector(a)[i].  For example, matrix(vector(1,3,2,4,6,5),2)[vector(1,2,6)]
yields vector(1,3,5).

Except in this case, it is an error when there are fewer subscripts than
dimensions.

@@@@subscripted_factor#Subscripted factor
When a is a factor and I is an appropriate vector of subscripts, a[I] is
a factor.  For example, anova("{y[-1]} = {a[-1]}") carries out an
analysis of variance omitting the first case.  See topics factor(),
anova() and 'models'.  The "official" number of levels of a[I] is the
same as for a, even when max(a[I]) < max(a).

@@@@matrix_and_array_subscripts
                      Matrix and Array Subscripts
You can also use a matrix as a single subscript in square brackets.  If
x is a vector, matrix or array with ndim dimensions, and Sub is a nrows
by ndim matrix of positive integers, then x[Sub] is a vector of length
nrows(Sub), whose i-th element x[Sub][i] is
   x[Sub[i,1],Sub[i,2],...,Sub[i,ndim]]
For example, if x is n by n, x[hconcat(run(n),run(n))] is equivalent to
diag(x) and x[hconcat(run(n),run(n,1))] extracts the cross diagonal of
x.  There can be no MISSING values in Sub.

More generally, if Sub is an array of positive integers whose last
dimension has length ndim, x[Sub] is an array with ndims(x[Sub]) =
ndims(Sub) - 1 with i,j,...,k-th element x[Sub][i,j,...,k] =
   x[Sub[i,j,...,k,1],Sub[i,j,...,k,2],...,Sub[i,j,...,k,ndim]].

See select() for a way to select a the k[i]-th element in the i-th row
of a matrix, when k is a vector of positive integers.

@@@@use_with_structure#Use with structure
A structure may have a single scalar or vector subscript which selects
components of the structure in the same way a scalar or vector subscript
selects elements of a vector.  See topic 'structures'.

@@@@assignment_to_subscripts
                        Assignment to Subscripts
You can assign to subscripts as well as extract from them.  For example,
if y is a matrix with at least 3 rows y[run(3),] <- 0 sets the first 3
rows of y to 0.  y[-vector(run(5),run(16,20)),] <- ? sets rows 6 to 15
and beyond 20 to MISSING.  A statement like 'y <- x[2,] <- 3' sets row 2
of x to all 3's and y to a row vector of 3's with dim(y)[2] = dim(x)[2].

When y is a structure, y[J] <- x changes components of y.  See subtopic
'assignment:"assignment_to_structure_components" for details.

Although you can use matrix subscripts in assignments to subscripts, you
cannot use array subscripts where more than 2 dimensions exceed 1.

@@@@see_also#Cross references
See topic 'assignment' for details on assignment to subscripts,
including assignment to subscripted components of a structure.
@@@@______

====sum()#descriptive statistics
%%%%
sum(x [,squeeze:T] [,silent:T,undefval:U]), x REAL or LOGICAL or a
  structure with REAL or LOGICAL components, U a REAL scalar
sum(x, dimensions:J [,squeeze:T] [,silent:T,undefval:U]), vector of
  positive integers J
sum(x, margins:K [,squeeze:F] [,silent:T,undefval:U]), vector of
  positive integers K
sum(x1,x2,... [,silent:T,undefval:U]), x1, x2, ... REAL or LOGICAL
  vectors, all the same type.
%%%%
@@@@usage#Usage
sum(x) computes the sum of the elements of a REAL or LOGICAL vector x.

If x is LOGICAL, True is interpreted as 1.0 and False as 0.0 and sum(x)
is the number of elements of x that are True.

If x is a m by n matrix, sum(x) computes a row vector (1 by n matrix)
consisting of the sum of the elements in each column of x.

If x is an array with dimensions n1, n2, n3, ..., y <- sum(x) computes
an array with dimensions 1, n2, n3, ... such that y[1,j,k,...] =
sum(x[i,j,k,...], i=1,...,n1).  This is consistent with what happens
when x is a matrix.  Note: MacAnova3.35 and earlier produced a result
with dimensions n2, n3, ... .

sum(x, squeeze:T) does the same, except the first dimension of the
result (of length 1) is squeezed out unless the result is a scalar.  In
particular, if x is a matrix, sum(x,squeeze:T) will be identical to
vector(sum(x)), and if x is an array, sum(x,squeeze:T) will be identical
to array(sum(x),dim(x)[-1]).

sum(NULL) is NULL.  See topic 'NULL'.

sum(a,b,c,...) is equivalent to sum(vector(a,b,c,...)) if a, b, c,
... are all vectors.  They must all have the same type, REAL or LOGICAL
or be NULL.  sum(NULL, NULL, ..., NULL) is NULL.

sum(x, silent:T) or sum(a,b,c,...,silent:T) does the same but suppresses
warning messages about MISSING values or overflows.

If all the elements of a vector x are MISSING, sum(x) is 0.0.

sum(x, undefval:U), where U is a REAL scalar does the same, except the
returned value is U when all the elements of x are MISSING.

@@@@dimensions_keyword#Keyword 'dimensions'
sum(x, dimensions:J [,squeeze:T] [,silent:T] [,undefval:U]) sums over
the dimensions in J = vector(j1,j2,...,jn) where j1, ..., jn are
distinct positive integers <= ndims(x).  Without 'squeeze:T', the result
has the same number of dimensions as x, with dimensions j1, j2, ..., jn
of length 1.  With 'squeeze:T', these dimensions are removed from the
result.  The order of j1, j2, ... is ignored.

It is an error if max(J) > ndims(x) or if there are duplicate elements
in J.

For example, if x is a matrix, sum(x, dimensions:2) computes the row
sums as a nrows(x) by 1 matrix and sum(x, dimensions:2,squeeze:T)
computes them as a one dimensional vector.

@@@@margins_keyword#Keyword 'margins'
sum(x, margins:K [,squeeze:F] [,silent:T] [,undefval:U]) sums over the
dimensions not in K = vector(k1, k2, ..., km), where k1, ..., km are
distinct positive integers <= ndims(x).  This computes marginal totals
for the margins specified in K.

Without 'squeeze:F', only the dimensions in K are retained in the
result.  Otherwise the other dimensions are retained but have length 1.
This is opposite from the default with 'dimensions:J'.

It is an error if max(K) > ndims(x) or if there are duplicate elements
in K.

@@@@structure_argument#Structure argument
If x is a structure, sum(x [,dimensions:J or margins:K] [,squeeze:T or
F] [,silent:T] [,undefval:U]) computes a structure, each of whose
components is sum() applied to that component of x.  All the components
of x be of the same type, REAL or LOGICAL.

@@@@examples#Examples
Examples:
If x is a n by m matrix

  Cmd> r <- x - sum(x)/sum(!ismissing(x))

computes the matrix of the residuals of x[i,j] from the column means.
When there are no MISSING values, divide by nrows(x)

If x is a n by 4 by 5 array,

  Cmd r <- x - sum(x)/sum(!ismissing(x))

computes an array with r[i,j,k] = the residual of x[i,j,k] from the
mean of all x[i,j,k] with the same values for j and k.  That is, it
treats x analogously to a 4 by 5 array of vectors of length n.  See
topic 'arithmetic'.  When there are no MISSING values, divide by
dim(x)[1].

If z is a vector of integers,

  Cmd> sum(z == run(min(z),max(z))')

computes a row vector giving the frequency distribution of the values in
z.

  Cmd> a # 2 by 2 by 3 array with labels
                 C1          C2          C3
  A1 B1           9           5           7
     B2           9          12          11
  A2 B1           4          11          10
     B2          11          15           9

  Cmd> sum(a,dimensions:2) # sum over dimension 2; 2 by 1 by 3 result
                  C1          C2          C3
  A1 (1)          18          17          18
  A2 (1)          15          26          19

  Cmd> sum(a,margins:vector(1,3),squeeze:F) # same as preceding
                  C1          C2          C3
  A1 (1)          18          17          18
  A2 (1)          15          26          19

  Cmd> sum(a,dimensions:2,squeeze:T) # sum over dim 2; 2 by 3 result
              C1          C2          C3
  A1          18          17          18
  A2          15          26          19

  Cmd> sum(a,margins:vector(1,3)) # same as preceding
              C1          C2          C3
  A1          18          17          18
  A2          15          26          19

@@@@see_also#Cross references
See also prod(), tabs()
@@@@______

====svd()#matrix algebra
%%%%
svd(x [,left:T or F,right:T or F, all:T, maxit:N, nonconvok:T]), x a
  REAL matrix, N > 0 an integer
%%%%
@@@@usage#Usage
svd() computes some or all of the parts (singular values, left singular
vectors and right singular vectors) of the singular value decomposition
(SVD) of a matrix.

svd(x) computes the vector of singular values in order of decreasing
size, of the m by n REAL matrix x.  When m < n, the last n - m elements
of values are 0.

svd(x,left:T) computes the singular values and the m by n matrix of
orthonormal left singular vectors in a structure with components
'values' and 'leftvectors'.  When m < n, the last n - m elements of
values are 0 as are the last n - m columns of leftvectors.

svd(x,right:T) computes the singular values and the orthogonal n by n
matrix of right singular vectors in a structure with components 'values'
and 'rightvectors'.  When m < n, the last n - m elements of values are 0
and the last n - m columns of rightvectors are orthonormal vectors
orthogonal to the first n columns, but are otherwise arbitrary.

svd(x,all:T) and svd(x,left:T,right:T) both compute a structure with
components 'values', 'leftvectors', and 'rightvectors'

svd(x,all:T,vals:F) computes a structure with components 'leftvectors'
and 'rightvectors' only.  Other combinations of all:T and other keywords
are possible and do what you would expect.

@@@@propagation_of_labels#Propagation of labels
If x has labels, the row labels of the matrices of left and right
singular vectors are the row and column labels of x, respectively.  The
column labels are numerical.  The vector of singular values is
unlabelled.  See topic 'labels'.

If l and r are the matrices of left and right singular vectors and s is
the vector of singular values then they satisfy (except for rounding
error) l %*% dmat(s) %*% r' = x and l %c% l = r %c% r = I-sub-m (when m
< n, only the upper left m by m block of l %c% l is I-sub-m).

@@@@non_convergence
                            Non-convergence
It is possible for the algorithm used by svd() not to converge, although
it rarely happens.  When it happens, the message
  ERROR: singular value algorithm in svd() did not converge
is printed.  Keywords 'maxit' and 'nonconvok' may be helpful in this
situation.

svd(x [,keywords], maxit:N), where N > 0 is an integer, computes the
singular value decomposition, but sets the maximum number of iterations
in the algorithm to N.  The default value is 30.  By using N > 30, this
may allow you to compute the SVD.

svd(x [,keywords] ,nonconvok:T) does the same, except failure to
converge is not an error.  When convergence does not occur, no message
printed and NULL is returned.  You can use this in a macro to make it
possible to recover from failure to converge, perhaps by invoking svd()
again using 'maxit' to increase the number of iterations.

@@@@see_also#Cross references
See also eigen(), eigenvals(), releigen(), releigenvals().
@@@@______

====swp()#matrix algebra,glm
%%%%
swp(x, n1 [, n2, ...] [, quiet:T, diag:d, tolerance:tol, keepswept:T]),
  x a REAL matrix, n1, n2, ... positive integers, or vectors of positive
  integers, tol > 0 a REAL scalar, d a REAL vector with positive
  elements
%%%%
@@@@usage#Usage
swp(x,Cols) uses a form of the Beaton SWP operator on the REAL matrix x
to compute a REAL result of the same size.  If x is m by n, Cols should
be a vector whose elements are positive integers <= min(m,n).

A single SWP of x on row and column k produces a matrix y of the same
size as x with

     y[i,j] = x[i,j] - x[i,k]x[k,j]/x[k,k], for i and j not equal to k
     y[i,k] = x[i,k]/x[k,k], for i not equal to k
     y[k,j] = -x[k,j]/x[k,k], for j not equal to k
     y[k,k] = 1/x[k,k]

The element x[k,k] is sometimes called a "pivot".

swp(x,Cols) does successive SWPs of x on Cols[1], Cols[2], ... rows and
columns.  If, attempting to SWP row and column M, abs(pivot) is found to
be too small in comparison with the abs(x[M,M]), the message
  WARNING: tolerance failure pivoting column M; not swept
is printed and that SWP is skipped.

The threshold for finding tolerance failure may be modified by keyword
'tolerance'; see below.

If x is n by n and non-singular, swp(x,run(n)) computes the inverse of x
(it can fail for certain non-positive definite but invertible matrices).

swp(x,Cols1, Cols2, ...), where Cols1, Cols2, ..., are vectors of
positive integers is equivalent to swp(x,vector(Cols1, Cols2, ...)).
For example, swp(cp,1,2,3,4) is equivalent to swp(cp,run(4)).

swp() can be very useful in regression and analysis of variance.

@@@@tolerance_keyword#Keyword 'tolerance'
swp(x,Cols,...,tolerance:Tol), where Tol is a small REAL scalar does the
same, but Tol is used in the test for what constitutes a small pivot.
Column M will be skipped if abs(pivot) < Tol*abs(x[M,M]), where pivot is
the value of x[M,M] just before a SWP of row and column M is attempted.

The default value of Tol is 10^(-12).

@@@@quiet_and_diag_keywords#Keywords 'quiet' and 'diag'
swp(x,Cols,...,quiet:T) does the same, but no warning message is printed
when a too small pivot is found.

swp(x,Cols,...,diag:d [,quiet:T]), where d is a REAL vector, does the
same, but the pivot for row and clumn M is compared with abs(d[M]) to
test whether a row and column will be swept.  The length of d must
always be min(nrows(x), ncols(x)).  This feature allows the sequence,
say,
  Cmd> d <- diag(x); x1 <- swp(x,1); x1 <- swp(x1,2,diag:d)
to be completely equivalent to
  Cmd> x1 <- swp(x,1,2)
Without diag:d, the comparison element for swp(x1,2) would be x1[2,2]
instead of x[2,2].

@@@@keepswept_keyword#Keyword 'keepswept'
swp(x,Cols,..., keepswept:T [,tolerance:Tol, ,diag:d, quiet:F]) does the
same, except that the result is a structure with components 'matrix' and
'sweptcols'.  Component 'matrix' is the swept version of x.  Component
'sweptcols' is a vector of integers, with abs(sweptcols[i]) the number
of the i-th row and column swept.  sweptcols[i] < 0 if and only if row
and column abs(sweptcols[i]) failed the tolerance check.  No warning
message is printed unless 'quiet:F' is an argument.

The use of 'keepswept:T' may allow you to compute a generalized inverse
of a singular square matrix.

  Cmd> tmp <- swp(a, run(nrows(a)), keepswept:T)

  Cmd> b <- tmp$matrix; J <- (-tmp$sweptcols)[tmp$sweptcols < 0]

  Cmd> if(!isnull(J)){b[J,] <- b[,J] <- 0;;}

Now, even if a is singular, a %*% b %*% a should be a within rounding
error and b %*% a %*% b should be b within rounding error.

@@@@see_also#Cross references
See also solve(), qr().
@@@@______

====syntax%#syntax,control,general,character variables,logical variables,variables,missing values,null variables
%%%%
Type help(syntax) for a summary of the following aspects of MacAnova
syntax:
  Commands and Statements
  Variables
  Command Line
  Compound Commands
  MacAnova as a Language
  Side Effects of Commands
  Conditional Execution and Looping
  Types of Data
  Assignment of Values to Variables
  Organization of Data
  Subscripts
  Combining Data Items
  Keyword Phrases
  Indirect Reference to Variables and Constants
  Re-executing a Command Line
Type help(syntax:"?") for a list of subtopic names.
%%%%
@@@@commands_and_statements
                        Commands and Statements
A MacAnova command or statement is a sequence of characters typed in at
the keyboard followed by ';' or '<cr>' (the RETURN or ENTER key).  The
first character should not be '!' unless it is a "shell escape" (see
shell()).

Typical commands or statements are 'x <- vector(1.2,3.1,5.3,2.4)<cr>'
(assign the vector (1.2,3.1,5.3,2.4) to variable x), 'print(x)<cr>'
(print the value of variable x), 'regress("y=x1+x2+x3")<cr>' (compute a
regression of variable y on variables x1, x2 and x3), or 'y <-
3*x^2<cr>' (assign to variable y the value of 3 times x squared).

You may put several commands or statements separated by ';' on a single
line terminated by <cr>.  An example would be
  Cmd> regress("y=x"); plot(x,RESIDUALS)<cr>
When you press '<cr>', but not before, all the commands or statements in
the line are executed one after the other.

One type of statement consists solely of a number or an algebraic
expression involving numbers or variable names.  Examples are '17.3',
'3*y', 'sqrt(4+cos(-1.32))' and '3*log(640320)/sqrt(163)'.  The only
effect of this type of statement is to print out the value.  This allows
MacAnova to be used as a symbolic calculator.  Here are some examples:
  Cmd> 17.3
  (1)         17.3

  Cmd> 3*log(640320)/sqrt(163)
  (1)       3.1416

  Cmd> 3*y
  (1)       25.584       28.817       30.636

  Cmd> "Hello!"
  (1) "Hello!"

Below for brevity both commands and statements are usually just called
'commands'.

@@@@side_effects_of_commands
                        Side Effects of Commands
Some commands have "side effects" such as printing tables or creating
variables containing the results of computation.  For example, although
anova() returns only a NULL value (see topic 'NULL'), it has side
effects, namely the printing of an analysis of variance table and
creation of several named variables such as RESIDUALS, SS and DF.

@@@@variables
                               Variables
Data are stored in permanent or temporary "variables" with names of up
to 12 characters.  Typical names might be 'x1', 'data', 'weight' or
'time_of_day'.

The names of permanent variables start with a letter or '_', while the
names of temporary variables start with '@' followed by a letter or
'_'.  The remainder of a name consists of letter, digits or '_'.  Names
are case sensitive (for example, 'residuals' is a different name from
'Residuals'.  Some variables are "invisible".  See topic
'variables:"invisible"'.

Typically you will select names that are relevant to the problem such as
'weight', 'residuals', or 'depv'.

A name may not be the same as a command name.  For instance, you can't
use 'rep' as a variable name because there is a command 'rep'.

Typing the name of a variable that is not "invisible" prints out its
value.

See topic 'variables' for more details.

@@@@command_line
                              Command Line
The 'command line' consists of all the commands that are executed by a
single <cr>.  The command line follows the standard MacAnova prompt
"Cmd> ", and may, in fact be continued on several actual lines; see
next paragraph.

When a command line becomes longer than one physical line, you can just
keep typing as the characters wrap around to the next line.  Or, you
may continue a line by typing '\<cr>' and continuing on the next line.
(Nonwindowed versions will issue a continuation prompt "More> ".) If
the break is at the end of a command, you need to type ';' before
'\<cr>'.  

@@@@correcting_mistakes#Correcting mistakes
If you make a mistake, you may backspace to erase the error.  On
windowed versions, you can move the cursor with the mouse at any time
to make corrections anywhere in the command line.  

@@@@compound_commands
                           Compound Commands
A "compound command" is a sequence of one or more commands inside curly
brackets '{' and '}'.  For example
   {i <- i+1; plot(x[,i],y[,i])}
is a compound command.  Compound commands are used primarily with
control constructs such as 'if', 'for' and 'while'.

Once you have started typing a compound command by pressing '{' the
command line is not executed by <cr> before you type a matching '}'.
Below, '{...}'  represents an arbitrary compound command.

In a compound command, you can type <cr> at any place where a semicolon
';' would be appropriate; the compound command will not be executed
until you have pressed <cr> after the closing '}'.

You may nest compound commands ({...{...}...}).  None of them is
executed until you terminate the outermost compound command with '}' and
press <cr>.

A common mistake is to fail to terminate a compound command with '}'.
MacAnova appears to be "hung up".  Actually it is just waiting for you
to finish what you started.  Until the compound command is complete,
MacAnova has no way to recogonize that you are through typing the
command line.  You can either type '}<cr>' or press the interrupt key
and start over.

@@@@macanova_as_language
                         MacAnova as a Language
The organization of MacAnova commands can be considered as a "functional
language," in the sense that the components of commands are functions or
operators which take arguments or operands as inputs and may compute
values as outputs.

The arguments of (inputs to) a named command or macro are separated by
commas and enclosed in '(' and ')', as in 'print(x,y,z)'.  Some named
commands or macros require no arguments.  In this case you just put '()'
after the name, as in 'getoptions()'.  In MacAnova documentation,
including help() output, a named command or macro is referred to by its
name followed by '()', for example, 'log10()' and 'getmacros()'.

@@@@values_of_commands_and_compound_statements#Values of commands and compound statements
All commands, including compound commands (see below) have a value.  For
example, 'sqrt(3)' has the value 1.73205080756888 and '4*atan(1)' has
value 3.14159265358979.

Some commands such as print() and regress() have values which are NULL
(see topic 'NULL').  In addition, an explicitly empty command, ';;' or
'();' has a NULL value.  For obvious reasons, you can't use commands
with NULL values in algebraic expressions or comparisons or in other
contexts require data.

A named command that returns a non-NULL value is often referred to as a
"function."

A few functions (for example getseeds()) return an "invisible" value
that can be assigned but is not automatically printed when it is not
assigned.  See topic 'variables:"invisible"'.

The value of a compound command is the value of the last command in the
curly brackets.  If its last command is empty (';;' or '();'), a
compound statement has a NULL value.  You can use a compound command
which has a non-NULL value in an expression.  For example,
  Cmd> xbar <- {print(x); sum(x)}/n
prints x and computes xbar = sum(x)/n, because the value of '{...}' is
the value of 'sum(x)'.

Output from functions may be arithmetically combined (for example,
'cos(x) + 3*sin(y)') and the value of (output from) one function may be
an argument to (input for) another, (for example, 'cos(sqrt(x+y))').

See also topics 'arithmetic' and 'transformations'.

@@@@conditional_execution_and_looping
                     Conditional Execution and Looping
There are several syntax elements that you can use to control which
commands are executed and in what order.  Here is a brief summary:

 Conditional execution
   if(Logical){...}
   if(Logical){...}else{...}
   if(Logical){...}elseif(Logical){...}else{...}
 Looping
   for(Var,Vector){...}
   for(Var,start,end[,increment]){...}
   while(Logical){...}
 Escaping from a loop
   break, break n, breakall, breakif()
 Skipping to the end of a loop
   next, next n
 Leaving a macro, possibly returning a value
   return

Logical must be a LOGICAL scalar variable or expression such as 'i < 4'.
Vector must be a REAL vector and start, end and increment must be REAL
scalars.  See below for types of data.

The first '{' following 'if(...)', 'for(...)', and 'while(...)' must be
on the same line.

See topics 'if', 'for', 'while', 'break' and breakif() for more details.

@@@@data_types
                             Types of Data
There are several types of data, including REAL, LOGICAL, CHARACTER,
GRAPH, STRUCTURE and NULL.  In certain output, LOGICAL, CHARACTER, and
STRUCTURE are abbreviated as LOGIC, CHAR, and STRUC, respectively.

@@@@REAL_data
REAL data
REAL data elements are numbers and can be entered from the keyboard,
read from a data file, or computed by arithmetic expressions,
transformations and other functions or macros.  You enter numbers as
integers without a decimal point (-321), as decimal numbers (31.4159),
or using exponential notation (7.2e+9 = 7.2*1000000000).

You can separate digits by '_' for clarity, but not after 'e'.  Thus
123_456.789_1 is equivalent to 123456.7891.  See topic 'numbers' for
more information.

A missing value is represented by a special internal code named MISSING.
When entering data at the keyboard, you enter a missing value as '?'.
On output, a missing value usually printed as "MISSING" but you can
specify a different output coding, say "?", by setoptions(missing:"?")
(see setoptions(), subtopic 'options:"missing"').

Virtually all commands and operations pay at least token attention to
MISSING, although at present nothing is done that is more complicated
than omitting cases with MISSING or setting to MISSING a result item
corresponding to a MISSING input item.

You can do arithmetic on REAL data using the arithmetic operators '+',
'-', '*', '^' or '**', and '%%' (for example, a * (b + c)).  See
topic 'arithmetic'.

You can compare REAL data items using comparison operators '<', '>',
'==', '!=', '<=', and '>='.  Except for '==' and '!=', a comparison with
a MISSING value yields a MISSING LOGICAL value.  See topic 'logic'.

@@@@LOGICAL_data
LOGICAL data
LOGICAL data have values limited to True, False and MISSING and are
entered and printed as 'T' (True) or 'F' (False).  Comparison
expressions (for example 'a < 3') generate LOGICAL data as values.
See topic 'logic' for detailed information.

You can combine LOGICAL variables and expressions using logical
operators '&&', '||' and '!'.  For example, '(x > 3) && !(x > 5)' has
value True if and only if both (x > 3) and (x <= 5) are True, that is if
3 < x <= 5.  Similarly, '(x > 0) || (abs(x) == 3)' has value True if and
only if x > 0 or |x| = 3 (or both).

You can use LOGICAL data in arithmetic expressions and comparisons, with
True and False being translated as 1 and 0, respectively.  For example,
F*T is 0, 2*T is 2, and F < T is True .  Logical variables can also be
used in place of REAL variables as argument to some, but not all
functions such as sum(), prod() and max().

@@@@CHARACTER_data
CHARACTER data
A CHARACTER data element consists of a sequence of characters, that is
letters, numbers, punctuation or anything else that can be typed.  It is
sometimes called a "string."  When entering CHARACTER data you must
enclose each string in double quotes as in
  Cmd> greetings <- "Hello!"
The opening and closing double quotes are not part of the string.  You
include a double quote in a string by prefixing ('escaping') it with
'\'.  For example,
  Cmd> a <- "He said, \"Hello\""
assigns the string 'He said, "Hello"' to variable a.  You can include
characters '\', newline and tab by '\\', '\n' and '\t', respectively,
using a convention borrowed from Unix/Linux.  For example,
  Cmd> b <- "1\t2\t3"
assigns to b the string consisting of '1', '2', and '3' separated by tab
characters.

@@@@importance_of_closing_quote#Importance of closing quote
Once you have started typing a CHARACTER string with '"', MacAnova
interprets everything, including <cr>, up to the next (non-escaped) '"'
as part of the string.  It does not recognize the command line to be
complete until you have typed the closing '"'.

A common mistake is to forget to terminate a string with '"'; MacAnova
appears to "hang", doing nothing.  You need to type a closing '"' and
terminate the line or press the interrupt key and start again.

@@@@special_characters_in_strings#Special characters in strings
You can include in a string any character, even one you cannot type
directly, using the so called escaped octal representation of its
internal (ASCII) code.  For example, since 1*8 + 5 = 13, '15' is the
octal (base 8) representation of 13 and "\15" or "\015" is the character
(usually CR) with code 13.  Similarly, because '117' is the octal
representation for 1*8*8 + 1*8 + 7 = 79, the ASCII code for 'O', "\117"
is equivalent to "O".  Also acceptable are escaped hexadecimal
representations of the form "\xmn", where m and n are hexadecimal digits
(0 - 9, and a - f or A - F).  For example, "\117" and "\x4f" are both
equal to "O" (4*16 + 15 = 79).

@@@@comparison_of_character_data#Comparison of character data
You can compare CHARACTER data items using comparison operators '<',
'>', '==', '!=', '<=', and '>='.  The ordering of letters is based on
their ASCII representation with "A" < "B" < ... < "Z" < "a" < ... < "z".
For example, '"A" < "B"', '"a" < "B"' and '"foo" == "bar"' have values
True, False and False, respectively.  See topic 'variables' for more
detail.

@@@@graph_variables#Graph variables
A GRAPH variable encapsulate all the information needed to draw a graph
or other plot.  You can display the plot in GRAPH variable GraphVar by
'showplot(graphVar)'.  See topic 'graphs' for more information.

@@@@structure_variables#Structure variables
A structure is made up of one or more named data components that may be
of any type.  See topic 'structures' for details.

@@@@null_variables#Null variables
A NULL variable contains no data.  See topic 'NULL' for details.

@@@@assignment_of_values_to_variables#Assignment of values to variables
                   Assignment of Values to Variables
You assign values to a variable using the left pointing arrow '<-'
made up of the two characters "less than" and "minus".  For example,
'foo <- 5' assigns the value 5 to the variable foo.  If foo did not
previously exist, it is created; otherwise, its previous value is
discarded and foo is re-defined.  An expression of the form 'x <- 3',
say, is always interpreted as 'x <- 3' rather than as 'x < -3'.  If you
want the latter, be sure to put a space before '-3'.

You can string several assignments together.  For example,
  Cmd> a <- b <- 1
is interpreted from right to left, first assigning 1 to b and then
assigning the new value of b to a.

See topic 'assignment' for information about the value of an assignment
statement, assignment to subscript-selected elements of a variable, and
assignments to components of a structure, and topic 'arithmetic' about
arithmetic assignment operators <-+, <--, <-*, <-/, <-%% and <-^.

@@@@data_shapes
                          Organization of Data
REAL, LOGICAL, or CHARACTER data may be organized as scalars, vectors,
matrices, or arrays.  The transpose of a matrix or array x may be typed
as x' or as t(x).  Matrix multiplication operators (applicable only to
REAL data) are %*%, %c%, and %C%.

See also topics 'vectors', 'matrices', vector(), matrix(), array(),
dim(), ndims(), ismatrix(), nrows(), ncols(), 'transpose'.

Data may have vectors of labels for each coordinate.  In particular,
matrices may have row and column labels.  Labels propagate through
operations and functions in a fairly sensible way.  Labels are primarily
used in output .  See topic 'labels' for information.

@@@@subscripts
                               Subscripts
You refer to an element or set of elements of a vector, matrix, or array
by using subscripts -- numbers or variables enclosed in square brackets
'[...]' immediately following the variable name.

For example, 'x[3,4]' is the element in row 3 and column 4 of matrix x,
'x[vector(1,3,5),4]' consists of rows 1, 3 and 5 of column 5 of x,
'x[3,]' is row 3 of x and 'x[,4]' is column 4 of x.

You can assign values to subscripted elements, as in 'x[3,4] <- 17' or
'x[3,] <- 5'.  See topics 'matrices', matrix(), array(), 'transpose',
'subscripts', 'assignment'.

When x is a structure, you can use x[[J]] in place of x[J].  When x is
not a structure, x[[1]] is the same as x and x[[J]] is illegal unless J
= 1.

@@@@______
                          Combining Data Items
There are commands to combine several data items into a larger vector,
matrix, or structure.  See vector(), hconcat(), vconcat(), structure(),
strconcat().

@@@@keyword_use
                            Keyword Phrases
Some command arguments can be "keyword phases" in the form
'keyword:value'.  For example, on several commands that write numbers,
the argument 'nsig:8' specifies that up to 8 significant digits are to
be printed and 'format:"18.13g"' specifies a format with width 18 and 13
significant digits.

LOGICAL keyword phrases like 'keep:T' or 'coefs:F' are particularly
common.  These enable (T) or suppress (F) alternative actions of a
command.  See topic 'keywords' for details.

@@@@indirect_reference_to_variables_and_constants
             Indirect Reference to Variables and Constants
<<String>>, where String is a quoted string or CHARACTER variable whose
value is the name of a variable, refers indirectly to that variable. For
example, '<<"cos">>(PI/4)' and '<<"E">>+3' are equivalent to 'cos(PI/4)'
and 'E+3', and, after the command 'a <- vector("x1","x2","x3")' creates
a CHARACTER vector a, '<<a[2]>> <- 3' is equivalent to 'x2 <- 3'.

The following line creates variables x1, x2, and x3 from the columns of
matrix x.

  Cmd> for(i,run(ncols(x))){<<paste("x",i,sep:"")>> <- x[,i];;}

See topics paste(), 'for' and 'subscripts'.

Indirect reference works even with keywords and structure component
names.  For example, setoptions(<<"nsig">>:5) is equivalent to
setoptions(nsig:5) and, when Str is a structure with a component named
'x', Str$<<"x">> is equivalent to Str$x.

If String is "?", "T", "F", or "NULL", the value of <<String>> is
MISSING, True, False, or a NULL variable.  If String represents a
number, <<String>> is the value of the number.  For example
10*<<"-123.456">> has value -1234.56.  If String represents a CHARACTER
scalar of the form "\"string without non-escaped quotes\"", <<String>>
is equivalent to "string without non-escaped quotes".  For example,
"ABCD" == <<"\"ABCD\"">> is True.

More generally, String can contain one or more MacAnova expressions or
commands.  The commands are executed and the value of <<String>> is the
value of the last command in String.  In this case, <<String>>
essentially does the same as evaluate(String).  There are some
restrictions on what commands can appear in String.  See evaluate().
  Cmd> <<"sqrt(2*PI)">>
  (1)       2.5066

On Mac OS 9, you can use Option+\ and Option+| instead of << and >>,
respectively.

@@@@reexecuting_a_command_line
                      Re-executing a Command Line
Just before MacAnova accepts a new command line, the immediately
preceding command line is saved as macro LASTLINE.  This allows you to
re-execute the immediately preceding command line by typing LASTLINE()
Alternatively, you can used pre-defined macro redo(): redo() makes a
copy of LASTLINE as macro REDO() and then executes REDO().  You can
subsequently re-execute the same line one or more additional times by
typing REDO().  You cannot use redo() on two successive lines.  See
topics 'macros', redo().

On machines where macro edit() is defined, you can edit the immediately
preceding line and re-execute the modified version by
  Cmd> REDO <- edit(LASTLINE); REDO()
See topic edit().

@@@@see_also#Cross references
See also topics 'comments', 'interrupt', 'quitting'.
@@@@______

====t()#matrix algebra,operations
%%%%
t(x) is same as x', x a vector, matrix, array or structure
t(x,J), x an array or structure, and J a vector containing a permutation
  of run(p)
%%%%
@@@@usage#Usage
t(x), where x is a vector, matrix, array or a structure, is equivalent
to x'.  See topic 'transpose'.

y <- t(x, J), where x is an array with p dimensions and J is an integer
vector containing a permutation of run(p), sets y to a copy of x with
the dimensions permuted.  y is an array with dimensions dim(x)[J] and,
when I is a vector of p integers with 1 <= I[j] <= dim(x)[J[j]],
  y[I[1],I[2],...,I[p]] = x[I[J[1]], I[J[2]],..., I[J[p]]].

For example, when x has three dimensions, and J = vector(3,1,2),
dimension 1 of y is dimension 3 of x, dimension 2 of y is dimension 1 of
x, and dimension 3 of y is dimension 2 of x.

t(x,j1,j2,...,jk) is equivalent to t(x,vector(j1,j2,...,jk)), where j1,
..., jk are scalars or vectors.

When p >= 2, t(x,run(p,1)) is equivalent to t(x) and x'.  When p = 1,
t(x) and x' are 2 dimensional with one row, but t(x,run(2,1)) is
illegal, since length(J) = 2 != ndims(x) = 1.

@@@@structure_argument#Structure argument
When x is a structure, all of whose non-structure components are arrays
with the same number of dimensions, t(x,J) is a structure of the same
shape and with the same component names as x, with each non-structure
component a copy of the corresponding component of x with dimensions
permuted.

@@@@examples#Examples
Examples:
  Cmd> x <- array(run(24),4,3,2) # x has dimensions 4, 3, 2

  Cmd> y <- t(x,vector(3,1,2)) # y has dimensions 2, 4, 3

  Cmd> i1 <- 2; i2 <- 2; i3 <- 3;vector(y[i1,i2,i3],x[i2,i3,i1])
  (1)          22          22

  Cmd> i1 <- 1; i2 <- 4; i3 <- 2;vector(y[i1,i2,i3],x[i2,i3,i1])
  (1)           8           8

@@@@see_also#Cross references
See also topics array(), 'vectors', 'matrices', 'subscripts'.
@@@@______

====t2int()#probabilities,descriptive statistics,confidence intervals
%%%%
t2int(x1,x2,Coverage [, pooled:F]), x1 and x2 REAL vectors or matrices
  with ncols(x1) = ncols(x2), 0 < Coverage < 1
%%%%
@@@@coverage#Coverage
t2int(x1,x2,Coverage), where x1 and x2 are REAL vectors, computes a (two
sided) t confidence interval for mu1 - mu2 with confidence coefficient
Coverage, where mu1 is the population mean of the data in x1 and mu2 is
the population mean of the data in x2.  A pooled estimate of the
standard error of the difference is used.  This assumes equal variances.

Coverage must be between zero and one.  The value is a vector of length
2 giving the lower and upper endpoints of the interval.

t2int(x1,x2,Coverage,pooled:F) computes a confidence interval for
mu1-mu2 based on the unpooled estimate sqrt(s1^2/n1+s2^2/n2) of the
standard error and Satterthwaite's approximate degrees of freedom.  It
does not assume equal variances.

If there are any missing values, they are omitted from the computation
and an informative message is printed

@@@@matrix_arguments#Matrix arguments
When x1 and x2 are REAL matrices with ncols(x1) = ncols(x2) = M,
t2int(x1,x2,Coverage [,pooled:T]) computes confidence intervals for each
column.  The result is a 2 by M matrix with the lower and upper limits
in rows 1 and 2, respectively.

@@@@see_also#Cross references
See also tint(), tval(), and t2val().
@@@@______

====t2val()#probabilities,descriptive statistics,comparisons
%%%%
t2val(x1,x2 [,df:T or pooled:F]), x1 and x2 REAL vectors or matrices
  with the same number of columns
%%%%
@@@@usage#Usage
t2val(x1,x2) computes the two-sample Student's t statistic for testing
the null hypothesis that the data in REAL vectors x1 and x2 have the
same population means mu1 and mu2.  The usual pooled estimate of
variance is used in computing the standard error of the difference of
means.  This assumes that the two variances are equal.

t2val(x1,x2,df:T) computes a structure with two components, 't' and
'df', containing the t-statistic and its degrees of freedom,
respectively.

t2val(x1,x2,pooled:F) computes a structure with components 't' and 'df'.
't' contains the t-statistic computed using the unpooled estimate
sqrt(s1^2/n1 + s2^2/n2) of the standard error of the difference of
means.  'df' contains Satterthwaite's approximate degrees of freedom.  A
test of H0: mu1 = mu2 based on t and df does not assume the two
populations have the same variance.

When there are missing values, they are omitted from the computation and
an informative message is printed.

@@@@testing_mu1-mu2_equals_delta#Testing H_0: mu1-mu2 = delta
When the null hypothesis is that mu1 - mu2 is some specific value other
than zero, say delta, then t2val(x1-delta,x2) will produce the correct t
value for that null hypothesis.  For example, if delta is -3, use
t2val(x1-(-3),x2 [,df:T or pooled:T]).

@@@@matrix_arguments#Matrix arguments
When x1 and x2 are REAL matrices with ncols(x1) = ncols(x2) = M, t2val()
computes two-sample t-statistics for each column separately.
t2val(x1,x2) returns a vector of length M.  t2val(x1,x2,df:T) and
t2val(x1,x2,pooled:F) return a structure with components 't' and 'df',
with each component a REAL vector of length M.

@@@@p_values#P values
P values may be computed using cumstu() or twotailt(), for example, by
  Cmd> result <- t2val(x1,x2,df:T);twotailt(result$t,result$df)
or
  Cmd> result <- t2val(x1,x2,pooled:F);twotailt(result$t,result$df)

@@@@see_also#Cross references
See also topics tval(), tint(), t2int(), cumstu(), and twotailt().
@@@@______

====tabs()#categorical data,descriptive statistics
%%%%
tabs(y [,a,b,...] [, mean:T, var:T, covar:T, count:T or n:T, stddev:T,\
  min:T, max:T, sum:T, prod:T]), y REAL vector or matrix, a, b,
  ... factors, LOGICAL or positive integer vectors
tabs(y [,a,b,...], all:T [,mean:F, var:F, ...] [,covar:T])
tabs(,a,b,...[,count:T or n:T])
%%%%
@@@@usage#Usage
tabs(y,a,b,c,...) computes summary statistics from data in REAL vector
or matrix y for each "cell" defined by grouping variables a, b, c, ... .
The values in a, b, c, ... must be positive integers < 32768, considered
as category levels, or MISSING.  In particular, a, b, c, ... can be
factors.  See factor().

By default, the output is a structure with components 'mean' containing
cell means, 'var' containing cell variances, and 'count' containing cell
sample sizes, but this can be modified by keywords.

The values in each component, including 'count', are based on the
non-MISSING elements of y.  When a cell has no non-MISSING values, the
count is 0 and any statistics computed are MISSING.

When y has MISSING elements, a warning message is printed.  When a
factor has elements that are MISSING, the corresponding value of y is
ignored and a warning message is printed.

When there are nFact grouping variables and y is a vector or a matrix
with 1 column, each component of the output is an array with nFact
dimensions.  When y is a matrix with nv = ncols(y) > 1, each component
is an array with nFact + 1 dimensions, the last of which is nv.

tabs(y,a,b,c,..., silent:T) does the same except warning messages are
suppressed.

@@@@logical_and_character_factors#LOGICAL and CHARACTER factors
Any grouping variable can be a LOGICAL vector, with False and True
corresponding to levels 1 and 2, respectively.  For example, tabs(y,
x1<=0, x2<=0) cross tabulates y according to the signs of x1 and x2.
See topic 'logic'.

When you want to cross tabulate data according to the values of either
non-integer REAL or CHARACTER vectors, use pre-defined macro
makefactor() to create corresponding factors.  See topic makefactor().

@@@@dimensions_of_output#Dimensions of output
When grouping variables a, b, c, ... are simple vectors and not factors
created by factor(), the length of each dimension is the maximum value
of the grouping variable.

When a grouping variable is a factor, the size of its dimension is the
"official" number of levels, even if the last level is empty, as can be
the case when it has the form f[J], where f is a factor and J is a
vector of subscripts.  See subtopic 'subscripts:"subscripted_factor"'.

@@@@use_without_factors#Use without factors
tabs(y), with no factor arguments, computes statistics for y as a whole.
Each component of the result is a scalar or a vector of length ncols(y).
This usage is similar to describe(y) except fewer statistics are
computed and the sample size component is called 'count' rather than
'n'.  See describe().

@@@@use_with_no_response#Use with no response argument
tabs(NULL,a,b,...) or tabs( ,a,b,...), with no first argument, just
computes the counts in each cell, returning a vector, matrix or array.
See topic 'NULL'.

@@@@controlling_what_to_compute
                Controlling which quantities to compute
When one of the keyword phrases 'mean:T', 'var:T', 'count:T',
'stddev:T', 'min:T', 'max:T', 'sum:T', 'prod:T' or 'covar:T' is an
argument, tabs() returns a REAL vector, matrix or array containing the
means, variances, counts, standard deviations, minima, maxima, sums,
products or covariance matrices of the values in each cell.  When more
than one of these keyword phrases are arguments, the result is a
structure with component names matching the keywords.

With 'covar:T', there can be no MISSING values in y and the result or
component 'covar' of the result is an array with nfact + 2 dimensions,
the last two of which are both ncols(y).

@@@@examples#Examples
Examples:
  tabs(y,a,b,mean:T,var:T,count:T) is equivalent to tabs(y,a,b).
  tabs(y,mean:T,var:T,count:T) is equivalent to tabs(y).
  tabs(y,a,b,mean:T) computes only a matrix of cell means
  tabs(y,a,b,mean:T,stddev:T,min:T,max:T) computes a 4 component
    structure of means, standard deviations and extremes for each cell
  tabs(y,a,b,sum:T,prod:T) computes a 2 component structure whose
    components are matrices of sums and products of all elements in
    each cell
  tabs(y,mean:T,stddev:T,silent:T) computes statistics for y as a whole;
    no warning message is printed when y has MISSING elements
  tabs(y,a,b,mean:T,count:T,covar:T) computes 3 dimensional arrays of
    cell counts and means and a 4 dimensional covariance matrix array
  tabs(y,covar:T) computes the ncols(y) by ncols(y) covariance matrix.

@@@@all_keyword#Keyword 'all'
Alternatively, you can use keyword phrase 'all:T' to compute all
quantities except the covariance matrix for each cell.  You can suppress
specific computations by, for example, 'sum:F' and 'prod:F', or force
computation of covariance matrices by 'covar:T'.

Example:
  tabs(y,a,b,all:T,stddev:F,min:F,max:F,sum:F,prod:F) is equivalent
  to tabs(y,a,b)

@@@@n_keyword#Keyword 'n'
You can use 'n:T' and 'n:F' instead of 'count:T' and 'count:F'.
However, with 'n:T', the corresponding component of the result will
still be named 'count'.

When y is NULL or absent, only 'count:T' or 'n:T' are permitted and at
least one factor is required.
@@@@______

====tan()#transformations
%%%%
tan(x [, degrees:T or radians:T or cycles:T]), x REAL or a structure
  with REAL components x in radians (default), cycles, or degrees as set
  by option "angles" or the optional keyword
%%%%
@@@@usage#Usage
tan(x) computes the tangents of the elements of x, where x is a REAL
scalar, vector, matrix or array.  The result has the same shape as x.

The argument is considered to be in units of radians, degrees or cycles
as determined by the value of option 'angles'.  The default is radians.
See subtopic 'options:"angles"'.

tan(x, radians:T), tan(x, degrees:T), tan(x, cycles:T) interpret x as in
the indicated units, regardless of the value of option 'angles'.

When any element of x is MISSING or is too large (> 5000000*PI radians
in absolute value), the corresponding element of tan(x) is MISSING and a
warning message is printed.

When x is a structure, all of whose non-structure components are REAL,
tan(x [,UNITS:T]), where UNITS is one of 'radians', 'degrees' or
'cycles', is a structure of the same shape and with the same component
names as x with each non-structure component transformed by tan().

@@@@see_also#Cross references
See topic 'transformations' for more information on tan(), including its
use with a CHARACTER argument.
@@@@______

====tanh()#transformations
%%%%
tanh(x), x REAL or a structure with REAL components
%%%%
@@@@usage#Usage
tanh(x) returns the hyperbolic sine of the elements of x, when x is a
REAL scalar, vector, matrix or array.  The result has the same shape as
x.  In terms of other functions, tanh(x) = (exp(x)-exp(-x))/
((exp(x)+exp(-x))

When any element of x is MISSING the corresponding element of tanh(x) is
MISSING and a warning message is printed.

When x is a structure, all of whose non-structure components are REAL,
tanh(x) is a structure of the same shape and with the same component
names as x, with each non-structure component transformed by tanh().

@@@@see_also#Cross references
See topic 'transformations' for more information on tanh().
@@@@______

====tek()#plotting
%%%%
tek()
%%%%
@@@@usage#Usage
tek() (no argument) puts your terminal in Tektronix 4014 emulation mode
if you are running MacAnova on Unix/Linux through a terminal emulator
with this capability.  The codes emitted are taken from
getoptions(tekset:T)[1].  See subtopic 'options:"tekset"'.

You normally don't need tek() since MacAnova automatically switches into
Tektronix mode when a graph is drawn.

tek() is implemented as a pre-defined macro (Unix/Linux versions only).

@@@@see_also#Cross references
See also topics vt(), vtx(), plot(), chplot(), lineplot(), showplot().
@@@@______

====tekx()#plotting
%%%%
texk()
%%%%
@@@@usage#Usage
tekx() puts a Unix/Linux work station Xterm terminal emulator in
Tektronix 4014 mode from vt100 mode.  You don't normally need tekx since
MacAnova recognizes when it is running in a Xterm environment (the value
of environmental variable $HOME is "xterm") and automatically switches
to Tektronix 4014 mode to draw a high resolution graph.

tekx is implemented as a pre-defined macro (Unix/Linux versions only)

@@@@see_also#Cross references
See also topics tek(), vt(), vtx(), 'graphs', 'unix'.
@@@@______

====time_series%#time series
%%%%
Type help(time_series) for information on the time series analysis
capability of MacAnova
%%%%
There are many MacAnova functions that are useful in time series
analysis.  In addition there are two files, tser.mac and arima.mac,
containing macros for doing frequency domain and time domain analyses.

@@@@functions_useful_in_time_series_analysis
                Functions useful in time series analysis
Fast Fourier transforms (FFT) for Complex, Hermitian, and Real series
  cft(), hft(), rft()
Functions for working with complex and Hermitian series and Fourier
transforms
  cconj(), creal(), cimag(), cpolar(), crect(), cprdc(), cprdcj(),
  cdivc(), cdivcj(), hconj(), hreal(), himag(), hpolar(), hrect(),
  hprdh(), hprdhj(), hdivh(), hdivhj() cmplx(), ctoh(), htoc(),
  unwind(), reverse(), padto(), rotate()
Autoregressive and moving average operators and their zeros
  autoreg(), movavg(), polyroot()
Other functions
  convolve(), partacf(), yulewalker()

Type, for example, 'usage(cft)' or 'help(cft)', to get a thumbnail
sketch or a complete description of cft().

@@@@macros_in_file_tser.mac
                    Macros for time series analysis
File tser.mac, distributed with MacAnova, contains the following macros:
  arspectrum()  Estimate spectrum of autoregression by solving the Yule-
                Walker equations
  autocor()     Compute autocorrelation function
  autocov()     Compute autocovariance function
  burg()        Estimate autoregression coefficients using Burg's
                algorithm and optionally compute the spectrum of the
                fitted moddel
  compfa()      Compute smoothed modified periodograms and, optionally,
                cross periodograms, using cosine tapering, with optional
                detrending
  compza()      Compute the Fourier transform of a cosine tapered
                series, optionally detrending
  costaper()    Compute a cosine taper with a specified amount of
                tapering
  crosscor()    Compute auto and cross correlation function
  crosscov()    Compute auto and cross covariance or correlation
                function
  crsspectrum() Compute smoothed periodgrams and cross periodogram with
                no tapering or detrending
  detrend()     Remove a polynomial trend in equally spaced time
  dpss()        Compute discrete prolate spheroidal sequences
  evalpoly()    Evaluate a real polynomial of a complex variable
  ffplot()      Plot a frequency function against frequency
  gettsmacros() Retrieves macros from tser.mac
  multitaper()  Compute multitaper spectrum estimates
  spectrum()    Compute smoothed periodograms with no tapering or
                detrending
  testnfreq()   Test whether its argument has prime factors > 29
  tsplot()      Plot time series against time

These can be retrieved by, for example, getmacros(multitaper) or
multitaper <- macroread("tser.mac","multitaper").

In addition, there are several macros for working with complex matrices
in fully complex form.  See subtopic 'matrices:"complex_matrices"' for a
list.

@@@@help_for_macros_in_tser.mac#Help for macros in tser.mac
Help for these macros is available in file tser.hlp.  You can get help
on these macros using help().  If you know a macro is in tser.mac, it
may be faster to use pre-defined macro tserhelp().  For example, to get
help on burg(), type tserhelp(burg).  See topic tserhelp() for details.
tserhelp() also can retrieve the following informational topics from
tser.hlp:

  bandwidth     Comments about the bandwidth and EDF of spectrum
                estimates
  complex_data  Information on representing complex data and series in
                MacAnova
  complex_fun   Summary of MacAnova functions for working with complex
                series
  fourier       Information concerning Fourier transforms
  hermitian     Information on complex series with Hermitian symmetry

See help() for information on direct use of help() to retrieve help
information from tser.hlp and arima.mac.

@@@@macros_in_file_arima.mac#Macros in file arima.mac
File arima.mac, distributed with MacAnova, contains the following
macros:
  acfarma()      Compute autocovariance function of ARMA model
  arima()        Fit ARIMA model or linear regression with ARIMA errors
                 by unconditional least squares or MLE estimation
  arimares()     Compute residuals from ARIMA model; used by macros
                 arima, hannriss, innovest.
  hannriss()     Fit an ARIMA model using the Hannan-Rissannen algorithm
  innovations()  Compute the coefficients for one step prediction in
                 terms of previous one-step prediction errors.  Used by
                 macro innovest
  innovest()     Fit an ARIMA model using the innovations algorithm
  levmar()       Fit a non-linear model by least squares using a form of
                 the Levenberg-Marquart algorithm
  moveoutroots() Fix up coefficients for a MA or AR operator so that all
                 the zeros are outside the unit circle in the complex
                 plane
  neg2logLarma() Compute -2log(L) from for ARIMA model with given
                 coefficients
  nlreg()        Fit a non-linear regression model by least squares.
  rhatcovar()    Compute variances and or covariances of sample
                 autocorrelations or the entire variance matrix of the
                 sample autocorrelation function using Bartlett's
                 formula
  rhatvar()      Compute variances of sample auto correlations using
                 Bartlett's formula
  specarma()     Compute spectrum of ARMA model

@@@@help_for_macros_in_arima.mac#Help for macros in arima.mac
File arima.mac serves as its own help file from which the help topics
can be retrived either by help() or by pre-defined macro arimahelp().
If you know a topic is in arima.mac, arimahelp() may be faster since it
searches only one file.  To get help on, say, macro arima(), type
arimahelp(arima) or help(arima).  See arimahelp() for details.

See help() for information on direct use of help() to retrieve help
information from tser.hlp and arima.mac.

@@@@see_also#Cross references
See also topics 'macros', macroread(), getmacros(), usage(),
macrousage().
@@@@______

====tint()#probabilities,descriptive statistics,confidence intervals
%%%%
tint(x,Coverage), x a REAL vector or matrix, 0 < Coverage < 1 a REAL
  scalar
%%%%
@@@@usage_and_example#Usage and example
tint(x,Coverage) computes a (two sided) t confidence interval with
coverage rate Coverage for the population mean of the data in REAL
vector x.  The result is vector(lowerLimit, upperLimit).

Coverage must be a REAL scalar between 0 and 1.

When x is a matrix with M columns, tint(x, Coverage) returns a 2 by M
matrix, with lower and upper limits in rows 1 and 2, respectively.

When there are missing values, an informative message is printed.

Example:
  Cmd> alpha <- .05; tint(x,1-alpha) # computes 95% conf. interval.

@@@@see_also#Cross references
See also tval(), t2val(), and t2int().
@@@@______

====toclip()#character variables,output
%%%%
toclip(x [, missing:Code, format:Fmt, sep:C1, linesep:C2]), Code,
  Fmt, C1, C2 quoted strings or CHARACTER scalars
%%%%
@@@@usage#Usage
toclip(x) is equivalent to CLIPBOARD <- x and puts a possibly multi-
lined CHARACTER representation of x in special variable CLIPBOARD.

When x is REAL, you can use keywords 'sep', 'missing', 'linesep', and
'format' that are permissible with paste(x,multiline:T,...).

In windowed versions, toclip() allows easy export of MacAnova data to
another application such as a spreadsheet.  For example, if x is a
10 by 5 REAL matrix that you want to export to a spreadsheet, after
'toclip(x)', you can select a 10 by 5 rectangle of cells in the
spreadsheet and select Paste in the Edit menu.  When the target
application has special requirements for representing MISSING or field
and line separators, you can use keywords to customize what gets put
on the Clipboard.

@@@@examples#Examples
Examples:
  toclip(x,missing:"NA") and toclip(x,missing:"-99") put x in CLIPBOARD
    with MISSING coded as NA and -99, respectively
  toclip(x,sep:",",format:".10f") puts x in CLIPBOARD with elements
    separated by commas and with 10 decimal places
  toclip(x,linesep:":",sep:",") puts x in CLIPBOARD with elements
    separated by commas and rows separated by colons.

@@@@see_also#Cross references
See also topics 'CLIPBOARD', fromclip(), paste(), clipreaddata().
@@@@______

toclip() is implemented as a pre-defined macro.

====toeplitz()#matrix algebra
%%%%
toeplitz(x), x a REAL vector.
%%%%
@@@@usage#Usage
toeplitz(x) computes an n by n Toeplitz matrix from a REAL vector x of
length n.  After a <- toeplitz(x), a is constant on the diagonals with
a[i,j] == x[|i-j| + 1].

The primary use of toeplitz() is to create a covariance matrix from an
auto-correlation function.  For example, if gamma0, gamma1, ... are the
variance and first n-1 autocovariances of a stationary time series
{x[t]}, then toeplitz(vector(gamma0, gamma1, ...))  computes the n by n
covariance matrix of the vector vector(x[1], x[2], ..., x[n]), or indeed
of vector(x[1+k], x[2+k], ..., x[n+k]) for any integer k.

@@@@see_also#Cross references
See also partacf(), yulewalker().
@@@@______

====trace()#matrix algebra
%%%%
trace(x), x a REAL square matrix
%%%%
@@@@usage#Usage
trace(x) computes the so-called trace of REAL square matrix x, that is,
sum(diag(x)) = x[1,1]+x[2,2]+...+x[k,k], when x is k by k..

@@@@see_also#Cross references
See also topics 'matrices', dmat(), diag(), det().
@@@@______

====transformations#transformations
%%%%
List of available transformations.  Argument x is REAL or structure with
REAL components. 't' => behavior depends on option 'angles'. '2' => has
two argument variant.
 Transformation          Result for REAL scalar x
   abs(x)                |x| = absolute value of x
   acos(x)        t      arccosine of x
   asin(x)        t      arcsine of x
   atan(x)        t 2    arctangent of x
   atanh(x)              inverse hyperbolic tangent of x
   ceiling(x)            least integer >= x
   cos(x)         t      cosine of x
   cosh(x)               hyperbolic cosine of x
   digamma(x)            digamma(x) = (d/dx)log(gamma(x))
   exp(x)                exp(x) = exponential function of x
   floor(x)              greatest integer <= x
   lgamma(x)             ln(gamma(x)) = log gamma function of x
   log(x)                ln(x) = base-e log(x) = natural logarithm of x
   log10(x)              base-10 log(x) = common log of x
   log2(x)               base-2 log(x) = log(x)/log(2)
   polygamma(x)   2      digamma(x) and (d/dx)^n digamma(x)
   round(x)       2      nearest integer to x
   sin(x)         t      sine of x
   sinh(x)               hyperbolic sine of x
   sqrt(x)               square root of x
   tan(x)         t      tangent of x
   tanh(x)               hyperbolic tangent of x
%%%%
@@@@available_transformations#Available transformations
Transformation are abs(x), acos(x), asin(x), atan(x) or atan(x,y),
atanh(x), ceiling(x), cos(x), cosh(x), digamma(x), exp(x), floor(x),
lgamma(x), log(x), log10(x), log2(x), polygamma(x) or polygamma(x,n),
round(x) or round(n,ndec), sin(x), sinh(x), sqrt(x), tan(x) and tanh(x)
where x (and y) are REAL variables or structures with REAL components.
x can also be a CHARACTER variable (see below).

Type usage(transformations) for one line descriptions of what these
transformations compute.  Type help(tranName), for example help(cos) or
help(sqrt), for help on individual transformations.

Trigonometric functions and their inverses are affected by the value of
option 'angles'.  See below and subtopic 'options:"angles"'.

@@@@vector_matrix_array_or_structure_argument#Vector, matrix, array, or structure argument
When x is a REAL vector, matrix or array, the result is REAL with the
same size and shape, with the elements of the result the transformations
of the elements of x.  For example, if x is a matrix, exp(x)[i,j] is
exp(x[i,j]).

When x is a structure, the result is a structure of the same shape and
with the same component names as x, whose components are the transformed
components of the argument.  See topic 'structures'.

@@@@missing_or_out_of_range_argument#MISSING or out of range argument
When any element of x is MISSING or outside the range of validity for
the function (for instance, < 0 for sqrt()), the corresponding element
of the result is MISSING and a warning message is printed.  See below
for more details.

@@@@propagation_of_labels#Propagation of labels
When x or any components have labels, the result has the same labels.
See topic 'labels'.

@@@@trigonometric_functions
                         Trignometric Functions
For sin(), cos() and tan(), the elements of x are interpreted as being
in radians, cycles or degrees according to the value of option 'angles'
whose default value is "radians".  Similarly, the values returned by
asin(), acos() and atan() are in the units specified by option 'angles'.
You can change the default by setoptions(angles:"degrees") or
setoptions(angles:"cycles").  See topic setoptions(), subtopic
'options:"angles"'.

All the trigonometric functions also allow one of 'degrees:T',
'cycles:T' and 'radians:T' as an extra argument.  These override the
units specified by option 'angles'.  For example, sin(30, degrees:T)
always returns 0.5 and asin(0.5, degrees:T) always returns 30.

@@@@illegal_or_too_large_arguments
                     Illegal or too large arguments
When the argument to a function is illegal (for example, sqrt(-1) or
atanh(1.2)), a warning message is printed and the result is set to
MISSING.

When the value of a function is too large to be represented in the
computer (for example, sinh(-3000)), a message is printed and the result
is set to MISSING.

Because of significant loss of precision in computing trigonmetric
functions of a large argument, the result of sin(x), cos(x) or tan(x) is
MISSING when |x| >= 5000000*PI radians (= 2500000 cycles = 900000000
degrees) and a warning message is printed.

When x > 4503599627370495 or x < -4503599627370495, floor(x) and
ceiling(x) are set to MISSING because of the impossibility of exact
representation of integers beyond these limits.  These limits may be
different on some computers.

@@@@CHARACTER_argument
                           CHARACTER argument
When the argument x to a transformation is a CHARACTER variable, the
result is a CHARACTER variable of the same size and shape with elements
usually involving the transformation name and the elements of x.

  Cmd> log10(vector("height","weight"))
  (1) "log10(height)"
  (2) "log10(weight)"

Any element of x that is "" or starts with '@', '(', '[', '{', '<', '/'
or '\' is not modified.

  Cmd> log(vector( "", "@[", "(1)"))
  (1) ""
  (2) "@["
  (3) "(1)"

This also works with two argument transformations such as atan(x,y) and
round(x,p), as long as both arguments are CHARACTER (p can be a number
on round()).

  Cmd> round("x","4") # round("x",4) works the same way
  (1) "round(x,4)"

This feature can be useful in creating labels for transformed data.

  Cmd> logx <- matrix(log(x),labels:structure(getlabels(x,1),\
        log(getlabels(x,2))))

This uses the row labels of x and transforms the column labels of x.

@@@@see_also#Cross references
See also topics 'arithmetic', 'syntax', atan(), hypot(), boxcox(),
polygamma(), round(), 'structures', rational(), labels, getlabels(),
matrix().
@@@@______

====transpose()#matrix algebra,operations
%%%%
x'  or  t(x), where x is a matrix
%%%%
@@@@usage#Usage
x' (x followed by a single quote or "prime") computes the transpose of x
if x is a matrix, that is the matrix y with y[i,j] = x[j,i].

When x is a vector of length n, x' is a 1 by n matrix, that is, a row
vector.

When x is an array with dimensions n1, n2, ..., nk, y <- x' computes an
array y with dimensions nk, ..., n1 such that y[i1,...,ik] is
x[ik,...,i1].  When x is a generalized matrix (see 'matrices'), so is
x', and matrix(x)' = matrix(x').

t(x) is synonymous with x'.

Provided ndims(x) > 1, t(x,run(ndims(x),1)) is equivalent to t(x) and
x'.  See also t().

@@@@transposition_with_matrix_multiplication#Transposition with matrix multiplication
Instead of x' %*% y and x %*% y' you can use x %c% y and x %C% y,
respectively which use less internal memory.  See topic 'matrices' for
more information on these matrix multiplication operators.

@@@@structure_argument#Structure argument
When x is a structure, each of whose components is REAL, LOGICAL, or
CHARACTER, x' computes a structure with the same shape and with the same
component names as x whose non-structure components are the transposes
of the corresponding components of x.

@@@@see_also#Cross references
See also topics array(), 'matrices', 'subscripts'.
@@@@______

====trideigen()#matrix algebra,time series
%%%%
trideigen(Diag, Subdiag [ [, start] , end], values:F or vectors:F),
   Diag, Subdiag REAL vectors, start and end positive integers
%%%%
@@@@usage#Usage
trideigen(Diag, Subdiag) computes the eigenvalues and eigenvectors of
the symmetric tri-diagonal matrix with diagonal Diag and sub- and
super-diagonal Subdiag. Diag and Subdiag must be REAL vectors with
length(Subdiag) = n - 1 or length(Subdiag) = n, where n = length(Diag).
In the latter case, Subdiag[1] is ignored.  The result is a structure
with components 'values' and 'vectors', similar to eigen.  The
eigenvalues are returned in decreasing order.

trideigen(Diag, Subdiag, vectors:F) computes only the eigenvalues,
returning a vector of length n.

trideigen(Diag, Subdiag, values:F) computes only the eigenvectors,
returning a n by n matrix.

@@@@limiting_eigen_values_computed#Limiting number of eigenvalues computed
trideigen(Diag, Subdiag, start, end) computes the i-th eigenvalues and
eigenvectors, for i = start, ..., end.  trideigen(Diag, Subdiag) is
equivalent to trideigen(Diag, Subdiag, 1, length(Diag)).

trideigen(Diag, Subdiag, end) is eqivalent to trideigen(Diag, Subdiag,
1, end).

@@@@application#Application
Command trideigen() was added specifically to make it straightforward to
compute discrete prolate spheroidal sequences (dpss) used in multi-taper
spectrum analysis.  For these, if W is the desired width, the following
computes the first K dpss
   d <- cos(2*PI*W)*(.5*run(-n+1,n-1,2))^2
   e <- .5*run(0,n-1)*run(n,1)
   dpssvecs <- trideigen(d,e,K,values:F)

@@@@comparison_with_eigen#Comparison with eigen()
The advantages of trideigen() over eigen() are (a) you do not need to
create the n by n tridiagonal matrix, and (b) you can obtain a subset of
the eigenvalues and eigenvectors.

@@@@see_also#Cross references
See also eigen(), releigen().
@@@@______

====trilower()#matrix algebra,variables,combining variables
%%%%
trilower(A), A a matrix
%%%%
@@@@usage#Usage
trilower(a) returns a matrix d of the same size and shape as a with
d[i,j] = a[i,j] for i >= j (on or below the diagonal) and d[i,j] = 0 for
i < j (above the diagonal).  Variable a must be a matrix but need not be
square.
                        [1   5   9]                   [1   0   0]
For example, when a is  [2   6  10] , trilower(a) is  [2   6   0] .
                        [3   7  11]                   [3   7  11]
                        [4   8  12]                   [4   8  12]

When a has type CHARACTER, elements above the diagonal are sent to empty
strings ("") instead of 0's.

trilower(a,T) or trilower(a,pack:T) returns the lower triangle (elements
a[i,j] with i >= j) of a in packed form.  Matrix a must be square, that
is, nrows(a) = ncols(b).  For example, when
               [1   4   7]
          a =  [2   5   8]  ,
               [3   6   9]
trilower(a) is vector(1, 2, 5, 3, 6, 9).

Note: keyword 'square' is not valid for trilower().

@@@@see_also#Cross references
See also triupper(), triunpack(), qr().
@@@@______

====triunpack()#matrix algebra,variables,combining variables
%%%%
triunpack(vec [, lower:T  or  upper:T]), vec a vector of length p(p+1)/2
%%%%
@@@@usage#Usage
triunpack(v) creates a symmetric square matrix from vector v which
specifies the upper triangular part of the matrix, including the
diagonal.  The length of v be of the form p*(p+1)/2, that is, it is a
'triangular number' and the dimension of the result is p by p.  For
example, triunpack(run(10)) produces the matrix
             [1   2   4   7]
             [2   3   5   8]
             [4   5   6   9]
             [7   8   9  10]

in which the upper triangle is filled column by column from run(10) and
the lower triangle is filled in symmetrically.

triunpack(v,upper:T) does the same, except the elements below the
diagonal are set to 0.

triunpack(v,lower:T) returns triunpack(v,upper:T)', whose elements above
the diagonal are 0.

When v is a CHARACTER vector, empty strings ("") are used instead of 0's
in filling out the other half.

@@@@example#Example
Example:
  Cmd> triunpack(run(10), upper:T)
and
  Cmd> triunpack(run(10), lower:T)
produce
             [1   2   4   7]          [1   0   0   0]
             [0   3   5   8]          [2   3   0   0]
             [0   0   6   9]   and    [4   5   6   0] , respectively.
             [0   0   0  10]          [7   8   9  10]

@@@@see_also#Cross references
See also triupper(), trilower(), qr().
@@@@______

====triupper()#matrix algebra,variables,combining variables
%%%%
triupper(A [,pack:T]), A a matrix
%%%%
@@@@usage#Usage
triupper(a) returns a matrix d of the same size and shape as a with
d[i,j] = a[i,j] for i <= j (on or above the diagonal) and d[i,j] = 0 for
i > j (below diagonal).  Variable a must be a matrix but need not be
square.
                        [1   5   9]                   [1   5   9]
For example, when a is  [2   6  10] , triupper(a) is  [0   6  10]
                        [3   7  11]                   [0   0  11]
                        [4   8  12]                   [0   0   0]

triupper(a,square:T) returns the m by m upper left block of triupper(a),
where m = min(nrows(a),ncols(a)).

When a has type CHARACTER, elements below the diagonal are sent to empty
strings ("") instead of 0's.

@@@@packed_output#Packed output
triupper(a,T) or triupper(a,pack:T) returns the upper triangle (elements
a[i,j] with i <= j) of a in packed form.  Matrix a must be square, that
is, nrows(a) = ncols(a).  For example, when
               [1   4   7]
          a =  [2   5   8]
               [3   6   9]

triupper(a,pack:T) is vector(1, 4, 5, 7, 8, 9).

@@@@see_also#Cross references
See also trilower(), triunpack(), qr().
@@@@______

====tserhelp()#general,time series
%%%%
tserhelp(topic1 [, topic2 ...] [,usage:T] [,scrollback:T])
tserhelp(topic, subtopic:Subtopics), CHARACTER scalar or vector
  Subtopics
tserhelp(topic1:Subtopics1 [,topic2:Subtopics2 ...])
tserhelp(key:Key), CHARACTER scalar Key
tserhelp(index:T [,scrollback:T])
%%%%
@@@@usage#Usage
tserhelp(Topic1 [, Topic2, ...]) prints help on topics Topic1, Topic2,
... related to macros in file tser.mac.  The help is taken from file
tser.hlp.

tserhelp(Topic1 [, Topic2, ...], usage:T) prints usage information
related to these macros.

tserhelp(index:T) or simply tserhelp() prints an index of the topics
available using tserhelp().  Alternatively, help(index:"tser") does
the same.

tserhelp(Topic, subtopic:Subtopic), where Subtopic is a CHARACTER scalar
or vector, prints subtopics of topic Topic.  With subtopic:"?", a list
of subtopics is printed.

tserhelp(Topic1:Subtopics1 [,Topic2:Subtopics2], ...), where Suptopics1
and Subtopics2 are CHARACTER scalars or vectors, prints the specified
subtopics.  You can't use any other keywords with this usage.

In all the first 4 of these usages, you can also include help() keyword
phrase 'scrollback:T' as an argument to tserhelp().  In windowed
versions, this directs the output/command window will be automatically
scrolled back to the start of the help output.

@@@@key_keyword#Keyword 'key'
tserhelp(key:key) where key is a quoted string or CHARACTER scalar lists
all topics cross referenced under Key.  tserhelp(key:"?") prints a list
of available cross reference keys for topics in the file.
@@@@______

tserhelp() is implemented as a predefined macro.

@@@@see_also#Cross references
See help() for information on direct use of help() to retrieve
information from tser.hlp.
@@@@______

====tinterval()#probabilities,descriptive statistics,comparisons
%%%%
tinterval(x[,y],cover:fraction,[upper:T or lower:T, pool:T|F])
%%%%
tinterval() computes a t-confidence interval for a population mean
or difference of population means, depending on whether one or two
variables are given as arguments.  By default, tinterval() computes
a two-sided interval, but you may choose one-sided alternatives
by using one of lowerb:T or upperb:T.

You specify the coverage rate via cover:value. You may choose pooled
or unpooled variances in two-sample tests via pool:T or pool:F.

The output is a vector containing the estimate and interval bounds.

Because the variance of the data must be known, these intervals are
rarely used in practical data analysis.

====ttest()#probabilities,descriptive statistics,comparisons
%%%%
ttest(x[,y],(upper:T or lower:T), null:val [pooled:T|F])
%%%%
ttest() performs a one- or two-sample t-test, depending on whether
one or two variables are given as arguments.  By default there is
a two-tailed alternative, but you may choose one-sided alternatives
by using one of twotail:T, lowertail:T, or uppertail:T.
You specify the null value via null:value.  For two-sample tests,
you may choose to pool variances or not pool via pooled:T or pooled:F.

The output is a vector containing the statistic, the degrees of
freedom, and the p-value.

====tval()#probabilities,descriptive statistics,comparisons
%%%%
tval(x [,df:T]), x a REAL vector or matrix
%%%%
@@@@usage#Usage
tval(x) computes the Student's t-statistic for testing the null
hypothesis that the data in REAL vector x have mean zero.  When x is a
matrix, the results is a vector with the t-statistics for each column of
x.

tval(x,df:T) produces a structure with two components, 't' containing
the t-statistic and 'df' containing the degrees of freedom.  When x is a
matrix, each component is a vector of length ncols(x).

When x contains MISSING values, an informative message is printed.

@@@@testing_h0_mu_equals_delta#Testing H_0:mu = delta
When the null hypothesis mean is something other than zero, say delta,
tval(x-delta) will produce the correct t value for that null hypothesis.
For example, to test H0: E[x] = 3, use tval(x-3).

@@@@p_values#P values
P values may be computed using cumstu() or twotailt(), for example, by
  Cmd> @result <- tval(x,df:T);twotailt(@result$t,@result$df)

@@@@see_also#Cross references
See also topics t2val(), tint(), t2int(), cumstu(), and twotailt().
@@@@______

====twotailt()#probabilities,descriptive statistics,comparisons
%%%%
twotailt(tval, df), tval a REAL scalar, df > 0 REAL.
%%%%
@@@@usage#Usage
twotailt(tval,df) computes the two tailed P value for a Student's t
value of tval with df degrees of freedom.  It is implemented as a macro.

In the simplest usage, tval and df are REAL scalars with df > 0.
However, if one argument is a scalar, the other argument can be a REAL
vector, matrix or array and the result has the same size and shape.
When both arguments are not scalars, they both must have the same size
and shape.

@@@@see_also#Cross references
See also cumstu().
@@@@______

====typeof()#variables
%%%%
typeNames <- typeof(arg1 [, arg2 ...]), arg1, arg2 ... arbitrary
  variables, including macros and built-in functions.
%%%%
@@@@usage#Usage
typename <- typeof(arg), where arg is any variable including macro and
built-in function sets typename to the type of arg, "CHARACTER",
"LOGIC", REAL", "STRUCTURE", "NULL", "MACRO", "FUNCTION", "UNDEFINED" or
"GRAPH".

typenames <- typeof(arg1, arg2 ...), where arg1, arg2, ... are any
variables, makes typenames a CHARACTER vector with length(typenames) =
number of arguments, with typenames[i] the name of the type of argument
i.

@@@@examples#Examples
Examples:

  Cmd> a <- sqrt(2); typeof(a)
  (1) "REAL"

  Cmd> b <- "pi"; typeof(b)
  (1) "CHARACTER"

  Cmd> typeof(a) == typeof(b) # test equality of types
  (1) F

  Cmd> typeof(PI,T,"type",structure(PI,T),LASTPLOT,notavar,typeof,help)
  (1) "REAL"
  (2) "LOGICAL"
  (3) "CHARACTER"
  (4) "STRUCTURE"
  (5) "GRAPH"
  (6) "UNDEFINED"
  (7) "FUNCTION"
  (8) "MACRO"

@@@@see_also#Cross references
See also topics nameof(), shapeof(), isarray(), ischar(), isdefined(),
isfactor(), isfunction(), isgraph(), islogic(), ismacro(), ismatrix(),
isname(), isnull(), isnumber(), isreal(), isscalar(), isvector().

====unique()#ordering,variables
%%%%
unique(x [,index:T, fuzz:d, relative:T]), x REAL, LOGICAL or CHARACTER,
  d >= 0 a REAL scalar
%%%%
@@@@usage#Usage
unique(x) computes a vector consisting of all the distinct non-MISSING
values in the REAL, LOGICAL or CHARACTER vector, matrix, or array x.
When x is REAL or LOGICAL, it is an error when all its elements are
MISSING.  If x1 contains the same values of x in a different order,
unique(x1) will return the same values as unique(x), but possibly in a
different order.

@@@@index_keyword#Keyword 'index'
unique(x, index:T) computes a vector J of positive integers such that
x[J] is the same as unique(x).  That is it finds the subscripts of the
unique non-missing elements of x.

@@@@inexact_matching#Inexact matching
unique(x, fuzz:d [, index:T]), where x is REAL and d >= 0 is a REAL
scalar does the same, except that, as x is scanned, x[j] is determined
to be different from x[i], 1 <= i < j only if abs(x[j] - x[i]) > d.  The
numbers returned may depend on the ordering of values in x.  That is,
for example, unique(x, fuzz:d) and unique(sort(x),fuzz:d) may return
different sets of numbers.

unique(x, fuzz:d, relative:T [, index:T]) does the same, except x[j] is
determined to be different from x[i] only if abs(x[j] - x[i]) > D, where
D = d*(abs(x[j]) + abs(x[i])).

@@@@examples#Examples
Examples:
  Cmd> unique(vector(5,3,1,2,4,2,5,7,2,7))
  (1)           5           3           1           2           4
  (6)           7

  Cmd> unique(vector(5.1,3,2.9,3.5,5,2.6), fuzz:.15)
  (1)         5.1           3         3.5         2.6

  Cmd> unique(sort(vector(5.1,3,2.9,3.5,5,2.6)), fuzz:.15)#order differs
  (1)         2.6         2.9         3.5           5

  Cmd> x <- vector(run(3), run(3)+1e-4)

  Cmd> unique(x,fuzz:4e-5)
  (1)           1           2           3      1.0001      2.0001
  (6)      3.0001

  Cmd> unique(x,fuzz:4e-5,relative:T)
  (1)           1           2           3      1.0001

  Cmd> unique(vector(T,T,T,F,T))
  (1) T       F

  Cmd> paste(unique(vector("B","C","A","B","D","A","A")))
  (1) "B C A D"

  Cmd> unique(vector("B","C","A","B","D","A","A"), index:T)
  (1)            1            2            3            5

If x is a REAL or CHARACTER vector,

  Cmd> a <- factor(match(x,unique(x)))

computes a factor each level of which corresponds to a unique value of
vector x and

  Cmd> a <- factor(match(x,sort(unique(x))))

does the same except the factor levels are in the same numerical or
alphabetic order as the elements of x.

@@@@see_also#Cross references
See also factor(), match()..
@@@@______

====unix%#general
%%%%
Type help(unix) for a summary of features specific to Unix/Linux
versions of MacAnova.
%%%%
@@@@unix_versions#Unix versions
Two Unix/Linux versions are distributed.  One runs in the command or
shell window where it was launched (usually an xterm or equivalent).
The other (the Carapace version) uses multiple command windows, high
resolution graphics windows, the mouse, menus, etc.

@@@@features_common_to_all_unix_versions
               Features common to all Unix/Linux versions
Various command line arguments are recognized.  These allow automatic
restoring of a workspace, suppressing the startup message, etc.  See
topic 'launching'.

MacAnova recognizes options, file names and path names specified in
environmental variable MACANOVA.  See topic 'customize'.

The startup file is Macanova.ini.txt in ~/MyMacAnovaFiles unless
flag -f has been used on the command line (see 'launching') or in
environmental variable MACANOVA.  See topic 'customize'.

The size of variables is limited only by the amount of memory and disk
space available.

Unless you use command line option -home (see 'launching') or include
-home in environmental variable MACANOVA (see 'customize'), MacAnova
pre-defines CHARACTER variable HOME to contain the user's home
directory.  HOME is used to expand file names of the form "~/path" by
substituting the value of HOME for '~'.  This allows you to refer to
files in your home directory such as stuff.data as "~/stuff.data"
regardless of the current directory.  When you redefine HOME, it changes
the expansion of "~/".  See topic 'files'.

File names starting with "~name/" are expanded similarly to the shell. 
That is, name is taken to be a Unix/Linux user name and "~name" is
expanded to the path name of the home directory of that user.  Redefining
HOME has no effect on this expansion.  See topic 'files'.

Pre-defined variables DATAPATHS, and DATAPATH are initialized with path
names that are installation dependent (see topic 'DATAPATHS').  You can
override these using options -path or -appdir on the command line (see
'launching') or in environmental variable MACANOVA (see 'customize').

@@@@non_windowed_version
                            Non-Windowed Version
High resolution graphics are implemented by emitting codes appropriate
for plotting on a Tektronix 4014 graphics terminal.  When this is not
appropriate, you are limited to displaying "dumb" plots and should use
setoptions(dumbplot:T).  See topic setoptions(), subtopic
'options:"dumbplot"'.

When MacAnova is running in an xterm, the graphics commands open a
pseudo Tektronix 4014 graphics window and draw in it, switching back to
the text window when <RETURN> is hit after the plot.  Be aware that
certain vendor replacements for xterm (for example, hpterm and dterm)
don't support Tektronix emulation.  To use high resolution graphics you
need to start up an xterm window.

You can execute Unix/Linux commands by prefixing the line with '!' in
the first position after the prompt or by using command shell().
Keyword phrase keep:T on shell() is recognized.  You must use keyword
phrase interact:T if the program being invoked expects any input from
you.  A line of the form '!command ...  ' is equivalent to
shell("command ...", interact:F).  See shell().

A pre-defined macro edit() is available which allows you to edit macros
and data from within MacAnova.

@@@@key_bindings#Key bindings
Depending on how it was compiled on a particular system, keyboard line
editing and history may be available as implemented using the GNU
Readline Library.  If so, the default editing mode is based on Emacs.
You can customize key bindings by creating a special file named
".inputrc" in your MyMacAnovaFiles directory.  This will be read each
time MacAnova starts up.  To enable editing based on Vi commands
instead of Emacs, put the following lines in this file:
   set editing-mode vi
   "k": previous-history
   "j": next-history
   "H": beginning-of-history
   "G": end-of-history

On some systems a standard environmental variable INPUTRC is defined and
keyboard bindings are taken from file $INPUTRC and not from .inputrc.
If that is the case and you want to customize key bindings, you will
need to define INPUTRC in your .profile or .cshrc file.  For csh, tcsh
or derivatives use
  setenv INPUTRC $HOME/.inputrc
For sh, ksh, bash and other similar shells, use
  export INPUTRC=$HOME/.inputrc

@@@@history_of_previsous_commands#History of previsous commands
When keyboard line editing is implemented, a "history" mechanism is also
available.  A certain number (default is 100) of previous commands are
saved.  Using the emacs editing mode, you can scroll backward by
pressing Ctrl+P (possibly also an up-arrow key) and scroll forward by
pressing Ctrl+N (down-arrow).  Under the vi editing mode, the
corresponding keys (when in vi command mode) are 'k' amd 'j'.  See
setoptions() for information on how to change the number of lines saved.

As part of this facility you also may have so-called file name
completion.  When you have partially typed a file name, press the Tab
key or press the Esc key twice and an attempt will be made to complete
it.  Press Tab twice or Esc four times and you will get a list of
possible completions.  See Readline documentation for information on
modifying key bindings using file .inputrc.  If you want to use the Tab
key as a regular key, but the following line in the .inputrc file:
"C-i": self-insert

@@@@Carapace_version
                               Carapace Version
This version is compiled using the Carapace library which in turn uses
the WxWidgets library. It allows multiple command/output and high
resolution graphics windows and uses menus, dialogs, the mouse, and
so forth in the usual way.  Commands are typed into the lower pane of
a command window, and output appears in the upper pane.  Output and
graphics windows can be printed and/or saved to files. 

Text in a command window can be copied to the clipboard.  Content of
a graphics window can be copied to the clipboard as a bitmap.  The
MacAnova variable CLIPBOARD is connected to text on the clipboard in
the sense that accessing CLIPBOARD returns a MacAnova string containing 
the text content of the clipboard, and assigning to CLIPBOARD writes
text to the clipboard.

@@@@see_also#Cross references
See topic 'carapace' for details on the Carapace version.  
@@@@______

====unlockvars()#general,variables
%%%%
unlockvars(a [,b,c...] [,silent:T]), a, b, c, arbitrary variables
%%%%
@@@@usage#Usage
unlockvars(var1, var2, ...) marks variables var1, var2, ... as being
unlocked variables so that they can be deleted or assigned to.  A
warning message may be printed if a variable is not locked.

unlockvars(var1, var2, ..., silent:T) does the same except warning
messages are not printed.  It is an error if any argument is an
expression or a function result.

@@@@see_also#Cross references
See also lockvars(), delete(), 'variables:"locked_variables"'
@@@@______

====unwind()#time series,complex arithmetic
%%%%
unwind(angleMat [, crit:Val]) where angleMat is REAL matrix and
  .5 <= Val < 1
%%%%
@@@@usage#Usage
unwind(angleMat) attempts to eliminate or reduce discontinuities (jumps
between rows) in each column of matrix angleMat, considered as being a
sequence of angles.

The assumed units of the angles are as specified by option 'angles'
("radians", "degrees", or "cycles").  For example, if angles are
measured in degrees, unwind(vector(350, 352, 359, 2, 1, 355)) is
vector(350, 352, 359, 362, 361, 355).  See subtopic 'options:"angles"'.

The operation of unwind() is controlled by the value Val of a criterion.
Let Jump = abs(angleMat[i,j] - angleMat[i-1,j]).  Then when Jump >
Val*Cycle, where Cycle is 2*pi radians, 360 degrees or 1 cycle,
angleMat[i,j] is increased or decreased by a multiple of Cycle so as to
bring the change less than Val*Cycle .  The default is Val = 0.75.

unwind(angleMat,crit:Val) uses Val for the unwinding criterion.  Val
must be between 0.5 and 1 cycles even when option 'angles' has value
"radians" or "degrees".

@@@@see_also#Cross references
See also topics hpolar(), cpolar(), subtopic 'options:"angles"'.
@@@@______

====updates*#
%%%%
Type help(updates_XXX), where XXX is old, 335, 336, 400, 401, 402, 403,
  404, 405, 406, 407, 410, 411, 412 or 413 for information on what
  changed in successive versions
%%%%
@@@@list_of_update_topics#List of update topics
Type help(updates_XXX) for information in changes in MacAnova as
sucessive versions were released.  should be one of old, 335, 336, 400,
401, 402, 403, 404, 405, 406, 407 or 410.
  XXX    Coverage
  old    Changes prior to the release of Version 3.35
  335    Changes made between release of Versions 3.35 and 3.36
  336    Changes made between release of Versions 3.36 and 4.00
  400    Changes made between release of Versions 4.00 and 4.01
  401    Changes made between release of Versions 4.01 and 4.02
  402    Changes made between release of Versions 4.02 and 4.03
  403    Changes made between release of Versions 4.03 and 4.04
  404    Changes made between release of Versions 4.04 and 4.05
  405    Changes made between release of Versions 4.05 and 4.06
  406    Changes made between release of Versions 4.06 and 4.07
  407    Changes made between release of Versions 4.07 and 4.10
  410    Changes made between release of Versions 4.10 and 4.11

Example:
  Cmd> help(updates_410)

@@@@see_also#Cross references
See also topic 'news'.
@@@@______

====updates_335*#general
%%%%
Type help(updates_335) for a summary of changes made between the
  releases of Versions 3.35 and 3.36 of MacAnova.
%%%%
@@@@changes_between_versions_3.35_and_3.36
     Summary of changes between releases of Versions 3.35 and 3.36

 New functions select(), trideigen(), and rename() (trideigen() was in
   late releases of 3.35)
 New function rsolve() and operators a %/% b, a %\% b
 New function probit() for doing probit analysis
 New function glmfit() includes anova(), logistic(), poisson(), and
    probit() as special cases
 New functions cumstudrng() and invstudrng() compute cdf and quantiles
    of studentized range distribution
 New functions usage() and macrousage() for getting brief usage
    information
 New function glmpred() generalizes regpred() to non-regression models
 New function glmtable() generalizes predtable(), allowing computation
    of standard errors
 New function xrows() allows computation of rows of the design matrix
    corresponding to active model
 New function gettime() allows timing of operations
 predtable() can now estimate marginal tables
 vecread() and matread() can input CHARACTER data and matprint () and
    matwrite() can output CHARACTER data
 New keywords on predtable() enable computation of standard errors and
   setting of covariate levels
 New function vector() is identical to cat() which is deprecated
 New function structure() is identical to makestr() which is deprecated
 Minor change in sum(), prod(), max(), min() operating on arrays;
   ndims(result) = ndims(arg), dim(result)[1] = 1
 Additional form, for(index,start,end){...}, of for loop
 <<charScalar>> now works with names of constants, that is with "T",
   "F", "NULL", and, for example, "123.5"
 ? == ? and ? != 1 are T, ? != ? and ? == 1 are F Formerly all were
   MISSING
 Precedence level of matrix multiplication put just above that of
   ordinary multiplication and division instead of the same level
   ('a*b%*%c' is treated as 'a*(b%*%c)')
 NULL variable type introduced along with special constant NULL
 Use of a LOGICAL subscript with all False values is now legal; the
   result is a NULL variable
 cat(), hconcat(), and vconcat() and isxxxx() (for example, isreal())
   can have NULL arguments
 outer() can now compute products of more than two arguments
 Functions such as print() and regress() that formerly had no value now
   have a type NULL value
 New special CHARACTER variable CLIPBOARD introduced On Macintosh,
   CLIPBOARD <- x copies data in x to the Clipboard and x <-
   vecread(string:CLIPBOARD) copies numerical data on the Clipboard to x
 Change in GLM output formatting and addition of keywords 'pvals' and
   'fstats' on GLM commands
 Univariate statistics available on manova(), controlled by keywords
   'fstats', 'pvals', and 'byvar'
 New keyword 'sssp' on manova() and default printing of large SS/SP
   matrices suppressed without 'sssp:T'
 New options 'missing', 'fstats' and 'pvals' on setoptions()
 Minor change made to estimation algorithm of robust(), as well as new
   keyword phrase trunc:c for setting truncation point
 robust() now gives approximate ANOVA table instead of a table of pseudo
   deviance
 New keyword phrase aliased:T on modelinfo gets information on aliased
   (pivoted out) X-variables
 New keyword phrase parameters:T on modelinfo() retrieves sample size
   vector after logistic() and probit()
 factor(v1, v2, ...) now is equivalent to factor(vector(v1,v2,...))
 New keyword phrase alt:T on help() switches to most recently used
   alternate help file
 New keyword 'string' on vecread(), matread(), macroread(), and
   inforead() allows "reading" from a CHARACTER variable
 New keywords 'badvalue' and 'silent' on vecread() allow silent
   detection of bad values in file or string
 New keyword 'name' on print(), write(), matprint(), and matwrite()
   allows greater flexibility in providing names on the header lines of
   variables printed or written to a file
 New keyword 'missing' on print(), write(), paste() can change how
   MISSING values are printed
 New keyword 'justify' on paste() allows left, right or centered
   justification of CHARACTER items
 New keywords 'multiline' and 'linesep' on paste() allow creation of
   CHARACTER vector or multi-line CHARACTER scalar from a vector or
   matrix
 New keyword 'ties' on rankits() and halfnorm()
 New keywords 'real', 'logic', and 'char' on isscalar(), isvector(), and
   ismatrix() allow for checking type at the same time as shape
 New keywords 'skip', 'stop', and 'quiet' on vecread()
 Default value of 'reorder' on rotation() changed to F
 New keyword phrase dollars:T' on macro() ensures all temporary
   variables end in $$
 Macro argument placeholders of form $01, $02, ... are replaced by NULL
   when argument is missing
 Macro hist() is now pre-defined
 New pre-defined macros toclip(), fromclip(), alltrue(), anytrue()
 hconcat(), vconcat(), diag(), dmat(), triupper(), trilower() and
   triunpack() now work with CHARACTER arguments
 A matrix or array subscript can be used with a CHARACTER variable
 Macintosh version has Font menu (in late release of 3.35)
 New options 'font' and 'fontsize' in Macintosh version
 Interactive editing of the current command and recall of previous lines
   (history) implemented on some versions
 Some versions have new option 'history' on setoptions()
 In Macintosh version, pre-defined macros are loaded as resources
 New internal representation of MISSING and greater checking input and
   results for overflow or non-representability
 Parser modified to make it less likely that memory usage will be
   inflated in macros and in loops
 Various bug fixes

@@@@see_also#Cross references
See also topic 'news'.
@@@@______

====updates_336*#general
%%%%
Type help(updates_336) for a summary of changes made between the
  releases of Versions 3.36 and 4.00 of MacAnova.
%%%%
@@@@changes_between_versions_3.36_and_4.00
     Summary of changes between releases of Versions 3.36 and 4.00

 Added capability for coordinate labels for variables
 New function getlabels() to retrieve labels
 New pre-defined macro haslabels() tests for presence of labels
   associated with a variable
 New option 'restoredel' changes default value of keyword 'delete' on
   restore()
 New option dumbplot changed default value of keyword 'dumb' on plotting
   commands
 New keyword labels on vector(), matrix(), array(), structure() and
   matread()
 Transformations such as sqrt() and log() now can have a CHARACTER
   argument
 Functions sort(), grade() and rank() now can have CHARACTER or
   structure of CHARACTER arguments
 vecread() interprets isolated period (".") as MISSING
 Keyword phrase bylines:T on vecread() allows reading file into a
   character vector, 1 element per line

@@@@see_also#Cross references
See also topic 'news'.
@@@@______

====updates_400*#general
%%%%
Type help(updates_400) for a summary of changes made between the
  releases of Versions 4.00 and 4.01 of MacAnova.
%%%%
@@@@changes_between_versions_4.00_and_4.01
     Summary of changes between releases of Versions 4.00 and 4.01

 bcprd(x1,...,xn) equivalent to bcprd(hconcat(x1,..., xn))
 New pre-defined character variable MACROFILES contains names of all
   standard files of macros
 New pre-defined character variable DATAPATHS contains one or more
   standard directories to search for files
 All commands reading files such as matread(), vecread(), macroread()
   and batch() use DATAPATHS
 New pre-defined macros addmacrofile() and adddatapath() add new
   elements to MACROFILES and DATAPATHS, respectively
 Macintosh version now initializes HOME, DATAPATHS, and MACROFILES using
   the name of the MacAnova folder
 Revised macro getmacros() searches all the files in MACROFILES for
   requested macros
 Variable and macro names may start with '_' but such names not normally
   listed by list() and listbrief()
 Keyword phrase invis:T on list() and listbrief() forces listing of
   variables with names starting '@' or '_'
 New menu items on Macintosh version (Save graph on File menu, GLM
   Options and Other Options on Options menu)
 Macintosh version now runs in background
 4 more basic graph windows and a second panel of graphs window on
   Macintosh version
 When a plotting command is writing PostScript a "prolog" is always
   written, even with new:F
 Keyword phrase screendump:filename on plotting commands writes PICT
   file on Macintosh
 On Macintosh, keyword phrases file:fileName,ps:F on plotting commands
   write PICT file but do not display plot
 Keyword phrase epsf:T on plotting commands causes encapsulated
   PostScript file to be written on specified file (Macintosh only)
 New plotting symbol (small cross)
 New keyword phrase 'notfoundok:T' on matread(), macroread(), and
   inforead()
 Various bug fixes

@@@@see_also#Cross references
See also topic 'news'.
@@@@______

====updates_401*#general
%%%%
Type help(updates_401) for a summary of changes made between the
  releases of Versions 4.01 and 4.02 of MacAnova.
%%%%
@@@@changes_between_versions_4.01_and_4.02
     Summary of changes between releases of Versions 4.01 and 4.02

 Alpha level Windows and Motif versions available with windowed
   interfaces similar to the Macintosh version
 New shortcut M^k for expressing models is equivalent to
   M.(1+M). ... .(1+M), where there are k "dotted" factors
 New plotting keywords xticks, yticks, xticklen, yticklen give some
   control over location and appearance of tick marks
 Symbol names starting with '_' and '@_' are now legal
 Symbols with such names are invisible; they are not normally listed by
   list() or listbrief() and their values can be seen only by an
   explicit print() or write()
 <<charScalar>> now works with strings whose values start and end with
   '"', that is, for example, <<"\"ABCD\"">> means the same as "ABCD"
 help() with no arguments prints a short message but not a list of all
   topics
 New keyword phrases depth:F and stats:T on stemleaf()
 The Macintosh version has new menu items Open Batch File and Spool
   Output To File on the File menu, Execute on the Edit menu, and Go To
   Prompt on the Windows menu
 Various bug fixes

@@@@see_also#Cross references
See also topic 'news'.
@@@@______

====updates_402*#general
%%%%
Type help(updates_402) for a summary of changes made between the
  releases of Versions 4.02 and 4.03 of MacAnova.
%%%%
@@@@changes_between_versions_4.02_and_4.03
     Summary of changes between releases of Versions 4.02 and 4.03

 New function keyvalue()
 New function kmeans()
 cumchi(x,df,lam) now computes non-central chisq cdf
 New keyword 'comments' on matprint(), matwrite() and macrowrite()
 Keyword 'n' a synonym of 'count' on tabs()
 Keywords 'nrows', 'ncols', and 'ndims' restrict list() and listbrief()
   to listing only variables with specified dimensions
 Keywords 'height' and 'width' on plotting commands allow control of
   size of "dumb" plots
 Parser change: a^b^c interpreted as a^(b^c)
 Environental variable MACANOVA scanned at startup (not on Macintosh)
 Interrupting of matrix multiplication and eigenvector or svd
   computations implemented on versions without a true interrupt
   (Windows, Motif, Macintosh, DJGPP)
 Various bug fixes

@@@@see_also#Cross references
See also topic 'news'.
@@@@______

====updates_403*#general
%%%%
Type help(updates_403) for a summary of changes made between the
  releases of Versions 4.03 and 4.04 of MacAnova.
%%%%
@@@@changes_between_versions_4.03_and_4.04
     Summary of changes between releases of Versions 4.03 and 4.04

 History mechanism added to windowed versions, allowing retrieval of
   previous commands using menu items Up History (F7) and Down History
   (F8) on the Edit menu Macintosh also recognizes Option+Up- and
   Down-Arrow
 matwrite(), matprint() and matread() enhanced so as to handle NULL
   variables and structures
 Alternative format for macros in a file removes the requirement that
   the number of lines be given explicitly
 New options 'labelstyle' and 'labelabove' allows you to change the
   style of coordinate labels when variables without labels are printed
 New option 'scrollback' allows automatic scrolling back to the start of
   output (Macintosh, Windows, Motif only)
 Coordinate labels of the form rep("@anything",dimi) are expanded when
   the variable is printed.  When "@anything" is "@(", "["@, "@{", "@<",
   "@/", or "@\\", the labels are similar to expansions of "(", "[",
   ..., except the expansion is done when the variable is printed and
   not when the labels are created
 New keyword 'scrollback' on help() allows scrolling back help output
   that scrolls off the top (Macintosh, Windows, Motif only)
 New keyword 'vertical' on boxplot() allows vertical alignment of boxes
   and whiskers
 New predefined macro vboxplot(), used like boxplot(), draws vertically
   oriented box plots
 Special Variable CLIPBOARD "connected" to system Clipboard in Windows
   and Motif versions
 New special variable SELECTION in Motif version is "connected" to the
   current selection in an X window in a similar way
 New option 'maxwhile' allows change of maximum number of repetitions of
   while loop
 New keyword phrase 'silent:T' on structure() and strconcat() suppresses
   warning messages
 New keyword phrase 'leftendin:T' on bin() counts values on left end of
   an interval as in the interval; default is count right end as in
   interval
 shell() implemented in Motif version and (still with problems) in
   Windows version
 New shell() keyword phrase 'keep:T' returns output of command executed
   as CHARACTER vector (not in Windows, Macintosh, limited memory DOS
   versions)
 New shell() keyword phrase 'interact:T' is required if user is to
   interact with command being executed
 Keyword phrase file:charScalar can be used to specify the file on
   vecread(), matread(), inforead() and macroread()
 Pre-defined macro readcols() revised to recognize string:charVec and
   file:charScalar in place of fileName; readcols() also recognizes
   other vecread() keyword phrases

@@@@see_also#Cross references
See also topic 'news'.
@@@@______

====updates_404*#general
%%%%
Type help(updates_404) for a summary of changes made between the
  releases of Versions 4.04 and 4.05 of MacAnova.
%%%%
@@@@changes_between_versions_4.04_and_4.05
     Summary of changes between releases of Versions 4.04 and 4.05

 New functions loadUser() and User() allow execution of user functions,
   that is, externally compiled routines written in C or Fortran
 New function asLong() creates a variable with new type LONG whose
   elements are true integers.  It is used to pass integers as arguments
   to a user function
 New function evaluate() allowing direct execution of strings
 Expanded scope of <<String>>; String can contain an expression or even
   several commands
 Out-of-line expansion of macros
 New option 'inline' and keyword 'inline' on macro()
 New keyword 'maxn' and increased default truncation point for
   samplesize()
 Check for size of arguments to floor(), ceiling(), sin(), cos() and
   tan()
 Text files, including help, data, macro, batch and asciisave() files,
   with line separators CR, LF, or CR/LF should be read correctly
 Escaping of non-printable characters in quotes when a macro is created
 Extended memory DOS version (DJGPP) can make high resolution plots when
   running under Windows or Windows 95
 Windows version recognizes long file names under Windows 95 and Windows
   NT
 q2 recognized as describe() keyword equivalent to median
 Macros added to file design.mac to compute expected mean squares and
   maximize a quadratic function subject to linear equality and
   inequality constraints
 Corrected bugs in Macintosh and Windows versions on handling Backspace,
   Delete and Del
 Corrected vecread() bug that made reading very large files unacceptably
   slow
 Corrected bug in rep(x,m), x a CHARACTER variable

@@@@see_also#Cross references
See also topic 'news'.
@@@@______

====updates_405*#general
%%%%
Type help(updates_405) for a summary of changes made between the
  releases of Versions 4.05 and 4.06 of MacAnova.
%%%%
@@@@changes_between_versions_4.06_and_4.06
     Summary of changes between releases of Versions 4.05 and 4.06

 New functions cumdunnett() and invdunnett() for computing P values and
   critical values for Dunnett's maximum t comparing a control with K-1
   treatments
 New function rpoi() for generating a pseudo-random sample from a
   Poisson distribution
 New function rbin() for generating a pseudo-random sample from a
   binomial distribution
 New functions gethistory() and sethistory() for retrieving and setting
   the internal list of previous command lines
 New function isarray() tests whether objects are arrays
 New pre-defined macro regcoefs() returns a matrix, derived from a GLM
   with no factors, of regression coefficients, standard errors, t
   statistics and optionally p-values
 for(i,NULL){...} is now allowed; the compound command {...} is simply
   skipped
 Functions sum(), prod(), max() and min() can have NULL arguments
 Explicitly NULL variable and structure subscripts, and negative
   subscripts that omit all values are no longer errors but create a
   NULL variable
 Subscript assignment of a scalar or NULL to a subscripted variable is
   legal when any subscript is either NULL or selects no elements (all
   False or negative omitting all values)
 New keywords 'stddev', 'm2', 'm3', 'm4', 'g1' and 'g2' on describe()
   allow computation of the standard deviation, sample 2nd, 3rd and 4th
   moments and coefficients of skewness and kurtosis
 New keywords 'nx', 'nvariates', 'nfactors' and 'hasconst' on
   modelvars() allow you to count the numbers of variates and factors in
   a model and find out if there is a constant term
 Variables and factors in models may be specified using notation {expr}
   where expr is a MacAnova expression Example: "{sqrt(y)} = x + {x^2}"
 A subscripted factor remains a factor
 New model abbreviations Pn(x) for a n-th order polynomial regression
   ("y=P3(x)") and Cn(x) for a n-th order periodic (harmonic) regression
   ("y=C2(2*PI*hr/24)")
 macrowrite() now writes "new style" headers, with no count of lines on
   the first header line
 Comment lines starting with '))' in files read by matread() and
   macroread() are not echoed to the screen unless quiet:F is an
   argument
 New usage changestr(Struct, name:value) in addition to previous usages
 New keyword phrase nomodelok:T on modelinfo() allows for a test of the
   existence of an active model
 First argument to tabs() can be NULL or missing to get just cell counts
 It is no longer legal to use batch() in a loop or a macro or with
   executable expressions following it
 Enhanced keyboard short cuts in windowed versions
 Focus problems in Windows and Motif version appear to have been
   overcome
 A problem causing crashes when the command window was saved in the
   Windows version appear to have been fixed
 A problem causing crashes when making plots on a Macintosh with system
   version earlier than 7 has been fixed
 Several bugs in treatment of missing values by a number of functions,
   including run(), rep(), array() have been corrected
 Missing values in for loop ranges are now detected
 Fixed bug in subscript assignment a[] <- b

@@@@see_also#Cross references
See also topic 'news'.
@@@@______

====updates_406*#general
%%%%
Type help(updates_406) for a summary of changes made between the
  releases of Versions 4.06 and 4.07 MacAnova.
%%%%
@@@@changes_between_versions_4.06_and_4.07
     Summary of changes between releases of Versions 4.06 and 4.07

 Function error() now adds "ERROR: " at start of message that does not
   already have it
 New syntax element 'next' skips to the end of a loop
 Variables may have descriptive notes.
 New functions appendnotes(), getnotes(), attachnotes() and setlabels()
 New function argvalue() similar to keyvalue() checks non-keyword macro
   arguments for type, shape and sign
 New pre-defined macro hasnotes()
 Enhancement to keyvalue() allows checking of shape and value as well as
   type of keyword macro argument
 Enhanced pattern matching using '*' and '?' in help(), list() and
   match()
 Keyword name to be matched by keyvalue() can contain the wild card
   characters '*' and '?'
 matprint() and matwrite() now write labels and notes
 macrowrite() writes notes attached to macros
 Left and right singular vectors from svd(x, all:T) have labels when x
   does.
 Slightly changed behavior of getlabels() and new keyword phrase
   'trim:T' to get previous behavior
 New keyword 'mantexp' on det()
 New keyword 'prompt' on batch()
 New keyword 'silent' on delete()
 New keywords 'prompt', 'go', 'bychars' on vecread()
 New keyword phrase 'exact':F on match() allows matching of wild card
   character '*' with CHARACTER arguments
 Keyword 'bywords' synonym for 'character' on vecread()
 New keyword phrase index:T on unique()
 New keyword phrase history:T or F on save() on asciisave() and new
   option 'savehistry' to provide default value for 'history'.  This
   allows for automatic saving and restoring of recently entered command
   lines.
 New keyword phrase problimit:smallVal on poisson(), logistic(),
   probit() and glmfit()
 New keyword 'notes' on vector(), matrix(), array(), macro() and all the
   plotting commands
 New command line options -p prompt and -bp batchPrompt
 On list(), size:T now lists totals
 lineplot() with lines:F interpreted as plot()
 save() and asciisave() now save tick information for GRAPH variables
   and restore() restores it
 New format for workspace files.  New keyword phrase v406:T on save()
   and asciisave() allows saving in previous format
 New help topics NULL, number, options, glm_keys and notes
 Both Motif and Windows versions based on WxWin 1.68
 Revised make and other installation files for easier porting to and
   installation on Unix/Linux systems
 Fixed bugs in handling MISSING values in cluster(), cholesky(), and
   kmeans().
 Fixed bug in rpoi() for small lambda.

@@@@see_also#Cross references
See also topic 'news'.
@@@@______

====updates_407*#general
%%%%
Type help(updates_407) for a summary of changes made between the
  releases of Versions 4.07 and 4.10 of MacAnova.
%%%%
@@@@changes_between_versions_4.07_and_4.10
     Summary of changes between releases of Versions 4.07 and 4.10

 New standard macro file arima.mac for time-domain time series analysis
   and nonlinear regression
 New function Mouse() allows interaction with graphics window in
   windowed versions and Unix/Linux versions which use Tektronix
   emulation
 New function getascii() translates from characters to ASCII codes
 New function isname() checks whether the value of a CHARACTER scalar is
   a legal MacAnova variable name.
 New function isfunction() checks whether its arguments are MacAnova
   functions.
 New function stringplot(x,y,s) is equivalent to addstrings(x,y,s,add:F)
 New syntax element 'return' allows leaving and returning a value from a
   macro anywhere in the macro
 When an apparent undefined macro is encounted, the files in CHARACTER
   vector MACROFILES may be searched, depending on the value of new
   option 'findmacros'.  If the macro is found, it is read in and
   executed.
 When certain errors occur in a macro, the macro name is automatically
   included in the error message.  This includes messages produced by
   function error() unless a new keyword phrase 'macroname:F' is an
   argument to error().
 You can assign directly to components of a structure selected by
   subscripts.
 Change in behavior of dim(x) when x is NULL or a structure with only
   NULL components.
 help() now ignores case in topic names, so that, for example,
   help(PLot) gives help on plot().
 tint() and tval() now accept a matrix first argument.
 t2int() and t2val() now accept matrices with matching numbers of column
   as first two arguments.
 New 'keep' option "intmodel" on screen() allows returning selected
   models as vectors of integers in the columns of a matrix.
 New option 'findmacros' controls whether macros are automatically
   searched for and whether a warning message is printed.
 New option 'tekset' specifies codes to switch a terminal emulator into
   and out of Tektronix 4014 mode.
 New "special" structure GRAPHWINDOWS preserves GRAPH variables
   associated with each graphics window.  You can assign to components
   of GRAPHWINDOWS to display or modify graphs in particular windows,
   and the value of GRAPHWINDOWS is saved by save() and restored by
   restore()
 New graphics keyword phrases 'borders:word" and 'ticks:word' control
   the sides of plots where the frame and ticks are drawn
 New graphics keyword phrases 'xticklabs:charvec' and
   'yticklabs:charvec' provide labels for ticks.
 New graphics keyword phrases 'logx:T' and 'logy:T' allow log scale
   plotting.
 New graphics keyword phrases 'symbols:ch' and 'strings:s'
 Graphics keyword phrases can now be combined in a structure using new
   keyword 'keys'
 Keyword phrase 'add:F' on addpoints(), addlines(), addchars() and
   addstrings() makes them behave like plot(), lineplot(), chplot() and
   stringplot()
 New keywords 'all', 'stddev', 'min' and 'max on tabs()
 New keyword phrase 'nofileok:T' on vecread(), matread(), macroread(),
   inforead() and read() makes failure to open a file not an error.
 New keyword phrase 'skipthru:c' on vecread() skips lines up to and
   including the first starting with c
 New keyword phrase 'singok:T' on solve() makes it return NULL when
   argument 1 is singular.
 New keyword phrase 'quiet:T' on det() and swp() suppresses the warning
   message when argument 1 is singular.
 New keyword phrase 'diag:realVec' on swp() specifies comparison values
   for testing singularity
 New keyword phrase 'keepswept:T' on swp() specifies that the swept
   matrix and columns swept are returned in a structure.
 New keyword phrases 'radians:T', 'degrees:T' and 'cycles:T' on
   trignometric functions and their inverses override value of option
   'angles'.
 New keyword phrase 'silent:T' on min(), max(), sum() and prod()
   suppresses warning messages.
 delete(var,return:T,invisible:T) deletes var and returns it as an
   invisible variable.
 New keyword phrase 'seasonal:n' on autoreg() and movavg() allows easier
   use of "seasonal" lag operators.
 New keyword phrase 'invisible:T' with 'return:T' on delete()
 New keyword phrase 'default:defVal' as an extra argument to keyvalue()
   provides a default value for a possible keyword in a macro argument
   list
 On iterative GLM commands poisson(), logistic(), probit(), glmfit() and
   ipf() without keyword phrase 'inc:T', TERMNAMES, DF and the labels
   put on SS now reflect the fact that only an overall model deviance
   and an error deviance are computed.
 Functions match() and unique() now work with LOGICAL arguments
 rankits(n:N) and halfnorm(n:N) are now equivalent to rankits(run(N))
   and halfnorm(run(N))
 Modified autoreg() and movavg() to interpret a NULL first argument
   (coefficients) as specifying the identity transformation
 Keyword phrase 'limits' on autoreg() and movavg() can have a scalar
   value, with a second element assumed to mark an end of the series.
 Each element of third argument to argvalue() and keyvalue() can specify
   more than one property, for example, "positive real".  Also there are
   new combined properties "number", "TF", "string" and "square"
 GLM side-effect variable SS always is labeled with complete term names.
 DOLLARS on the name line of a macro in a file directs that '$$' will be
   added to every temporary names starting with '@' unless '$$' is
   already there.
 ENDED on the name line of a macro or data set in a file indicates the
   macro or data set is followed by a line starting '%setName%', where
   'setName' is the name of the macro or data set.
 A line starting _E_N_D_O_F_M_A_C_R_O_S_ in a file of macros and data
   sets is now recognized by matread(), macroread() and read() as
   marking the end of macros and/or data
 Modified boxplot() to avoid overly "fat" boxes when fewer than 4
   horizontal or 5 vertical boxes are drawn
 Change to svd(x [...]) so it works with matrices x with nrows(x) <
   ncols(x)
 New option 'plotdelay' and command line flag -plotdelay on Motif
   version
 Some error messages now indicate the macro where the problem occurred
 Bug fixes in qr() and macro qrdcomp so they work with matrices x with
   nrows(x) < ncols(x)
 Fixed bugs in cprdc() and cprdcj() so they work correctly with
   arguments with an odd number of columns
 Fixed various interface bugs in the Windows version.

@@@@see_also#Cross references
See also topic 'news'.
@@@@______

====updates_410*#general
%%%%
Type help(updates_410) for a summary of changes made between the
  releases of Versions 4.10 and 4.11 of MacAnova.
%%%%
@@@@changes_between_versions_4.10_and_4.11
     Summary of changes between releases of Versions 4.10 and 4.11

 New macrofiles graphics.mac, math.mac, mulvar.mac, regress.mac
   including many new macros and some moved from MacAnova.mac which is
   greatly slimmed down
 New functions:
   setodometer() is useful for stepping through all combinations of
     factor levels and in finding mixed radix representations of
     integers.
   memoryinfo() provides information about memory usage
   alltrue() and anytrue() replace pre-defined macros with the same
     names
   log2() computes base 2 logarithms
 New predefined macros
   arimahelp, designhelp(), graphicshelp(), mathhelp(), mulvarhelp(),
     tserhelp() and regresshelp() make it easier to get help on macros
     in files distributed with MacAnova.
   readdata() is an alternative to readcols() for reading columns of
     data in a file
 Syntax changes
   Escaped hexadeimal integers (for example, "\x07") are now recongized
     in strings
   Change in behavior of StrLhs[j] <- StrRhs, when j selects one
     component of StrLhs and StrRhs is a structure with one component
 Changes to tabs()
   tabs(x [,keyword phrases]) with no factors is legal and computes
    statistics for x as a whole
   Keywords 'sum', 'prod' and 'covar' allow computation of sums,
    products and covariance matrices of data in each cell
 t(x, J), where x is an array and J is a permutation of run(ndims(x)),
   computes a "generalized transpose" of x, permuting the subscripts.
 Predefined macro makecols() can get variable names from column labels
   or from the first line of a CHARACTER argument.
 Predefined macro makefactor() transfers labels from its argument to the
   result, or, with 'labels:T' creates new labels from the values of its
   argument. 'labels:F' prevents any labelling of the output
 Changes to predefined macro hist()
  New keyword phrases:
   'outsideok:T' allows extreme points to be outside of bars
   'freq:T' sets bar heights to frequencies (counts)
   'relfreq:T' sets bar heights to relative frequencies (counts/n)
   'save:T' suppresses plot but returns structure with coordinates
   'draw:T' ensures plot made even with 'save:T'
  A length 2 vector argument 2 is interpreted as vector(anchor, width)
 Plotting command changes
  New keyword phrase 'silent:T' suppresses warning messages
  Data arguments x and y can now be NULL; no plotting is done
  New circle plotting character ("\10") and two sets of smaller
    plotting characters ("\11", ..., "\17", "\20") and ("\21", ...,
    "\27", "\30").  Small cross code changed to "\14".
  Keyword 'linetype' can have non-positive value; value n < 0 is
    the same as abs(n) except a warning message is supressed when
    lines are not being drawn; n = 0 is the same as n = -1.
 New Mouse() keyword phrase 'cancelok:T' directs that cancellation
   is not an error
 Keyword phrase 'fuzz:d' on match() and unique() allows inexact matching
 New paste() keywords 'iw', 'cw', 'fmt' and 'just' are synonyms for
   keywords 'intwidth', 'charwidth', 'format' and 'justify'
 New isreal(), isscalar(), isvector(), ismatrix() and isarray() keyword
   phrases 'integer:T', 'positive:T, 'negative:T' and 'nonneg:T' allow
   further testing of properties of variables
 New macrowrite(), matprint() and matwrite() keyword phrase
   'stripdols:T' allows for stripping '$$ from variable names in a macro
   when it is written to a file
 Keyword phrase 'macroname:T' can be used on print() and write()
 Changes to vecread() and/or readcols()
  New keyword phrases:
   'n:N' sets the maximum number of items that will be read
   'bypass:n' skips past n-1 lines starting with the stopping
    character
   'startline:M' ignores the first M-1 lines at start of the file or
    after the last stopping character skipped
   'byfields:T' changes the way REAL data is read from a file containing
    commas or non-numerical items.
  'NA' recognized as a MISSING value code
  'skip:"#"' is now the default for vecread() and readcols().  Use
    'skip:""' when there is no skipping character.
  A stop character is recognized with 'byfields:T' or 'bywords:T' only
    if it starts a field or word.
  readcols() can get variable names from the file being read
  'realorchar:T' on readcols() allows both REAL and CHARACTER variables
    to be read simultaneously
  New help topic 'vecread_keys'
 Predefined macro getmacros() works with quoted macro names
 matread() and read() now "expand" labels of the form '(', '[', '{',
   '<', '/', and '\' or starting with '@'
 inforead() keyword 'quiet' now has default value F
 New keyword phrase 'badkeyok:T' on vecread(), macroread(), matread(),
   read() and inforead() keeps unrecognized or duplicate keywords from
   being treated as errors
 New hconcat() and vconcat() keyword phrases labels:Labs and silent:T
   used like on matrix()
 New keyword phrase 'silent:T' on coefs(), secoefs(), contrast(),
   regpred(), glmpred(), predtable() and glmtable() suppresses advisory
   messages
 New cholesky() keyword phrase 'nonposok:T' causes NULL to be returned
   when the first argument is not positive definite.
 New keyword phrases for svd(), eigen(), eigenvals(), releigen()
  and releigenvals()
   'maxit:N' changes the allowed number of iterations
   'nonconvok:T' causes NULL to be returned on failure to converge.
 Minor changes in parsing keyword phrases in list() and listbrief()
 GLM side-effect variable DF labelled with term names
 Result of scalar OP scalar are not labelled, for all binary elementwise
   operations OP
 New command line option -open windowFile in the Windows and Motif
   versions loads the contents of windowFile into the command/output
   window.
 Change to parser to allow arguments to designated functions to be
   evaluated from within the function rather than while the argument
   list is being scanned before the function is invoked.
 Many changes in macros in macro files, most of them minor
 The command and model parsers are now maintained using Berkeley yacc.
 Various bug fixes, including three serious memory leaks, faulty
   recognition of term names when there are temporary variables in
   the model, an algorithm error related to qr() and an algorithm error
   in rpoi()

@@@@see_also#Cross references
See also topic 'news'.
@@@@______

====updates_411*#general
%%%%
Type help(updates_411) for a summary of changes made between the
  releases of Versions 4.11 and 4.12 of MacAnova.
%%%%
@@@@changes_between_versions_4.11_and_4.12
     Summary of changes between releases of Versions 4.11 and 4.12

 New functions primefactors() for factoring integers and goodfactors()
   for finding numbers with no prime factors > 29
 New function getfilename() returns the complete path name (or just the
   file name or just the path without the file name) of a file selected
   using a file navigation dialog box (only in windowed versions).  With
   keyword phrase 'last:T' it returns the name of the last file opened.
   With keyword phrase 'help:T' it returns the name of the current help
   file
 New function isnumber() checks whether CHARACTER scalars represent
   numbers.
 New options
   'excludeM' provides a default value for keyword 'excludeM' on
     boxplot(), describe() and stemleaf().  When True, the median
     is not considered in either half of a data set when computing
     quartiles.
   'matchdelay' controls length of time a matching parenthesis or
     bracket is highlighted in windowed versions
   'maxlinelen' changes the maximum length of lines that can be read
     from a file
   'keyboard' (Windows version only) controls what Alt Gr key
     combinations on non-US keyboards are recognized
 New pre-defined CHARACTER vector HELPFILES contains the names of most
   of the standard help files
 New pre-defined macro addhelpfile() adds a help file name at the
   beginning or end of HELPFILES
 New pre-defined macros help() and usage() use gethelp() and getusage()
   (see below) to scan all the files in HELPFILES for help and usage
   information
 New pre-defined macro clipreaddata() is like macro readdata() except it
   reads named vectors from the clipboard.
 rotate() and reverse() now work with a CHARACTER argument 1
 GLM related changes
  varnames(Model) now requires the Model be a valid GLM model.  It also
   correctly handles variables to be evaluated on-the-fly.
  varnames() recognizes keyword phrases 'stripat:T' and 'stripbrack:T'
   which modify how expressions and temporary variable names are
   handled
  modelinfo(termnames:T) returns full term names, including starting '@'
   if any
  delete(STRMODEL) clears internal information about lates GLM model fit
 ismissing(), rank(), rankits() and halfnorm() now propagate the labels
   of their arguments.  In addition, many functions such as sum(),
   prod(), cos() and sqrt() that transform structure arguments to
   structures of the same shape propagate any structure component
   labels.
 vecread(), matread(), macroread() and read() now print the file name
   read unless this is suppressed by 'printname:F' or 'silent:T'.
   This applies also to macros readdata(), readcols(), getdata() and
   getmacros().
 Change in match()
   Argument 2 can be a matrix and argument 1 is matched with each column
    separately
 Changes related to help() and usage()
   Functions help() and usage() have been renamed gethelp() and
    getusage().
   New pre-defined macros help() and usage() are used almost the same as
    gethelp() and getusage(), except they scan all files named in
    pre-defined CHARACTER vector HELPFILES.
   help keyword phrase 'index:helpfilename' prints an annotated index of
    a help file; the names of the indices for the standard help files
    are in pre-defined CHARACTER vector HELPINDICES.
   Keyword phrase 'usage:T' makes gethelp() and help() act like
    getusage() and usage()
   Keyword phrase 'silent:T' on gethelp(), help(), getusage() and
    usage() suppresses warning messages.
   Keyword phrase 'printname:T' on gethelp() and getusage() specifies
    that name the file where help is found is to be printed
   gethelp(), getusage(), help() and usage() all return an invisible
    LOGICAL scalar with value True only when at least one topic was
    found
   Almost all topics in help files have defined subtopics which you can
    selectively print using keywords.  Type 'help(gethelp:"subtopics")'.
   Topic names longer than 12 characters or that are control words such
    as 'if' and 'break' no longer need to be quoted.
   Moved some help items from macanova.hlp to userfun.hlp and added a
    new predefined macro userfunhelp()
   All special help macros such as designhelp() now recognize gethelp()
    keyword 'key'
 Change to usage()
   usage() has been renamed getusage() and a new pre-defined macro
    usage() has been added.  usage() is used like getusage() except it
    scans all files named in pre-defined CHARACTER vector HELPFILES
   getusage() and usage() return an invisible LOGICAL scalar with value
    True only when at least one topic was found
   Keyword phrase 'silent:T' suppresses warning messages.
 Changes to macrousage()
   macrousage() now returns an invisible LOGICAL scalar which is True
    only when at least one macro specified was found
   Any argument, not just the first, can be a CHARACTER variable whose
    elements are assumed to be the names of macros
 Changes to describe()
   Keyword phrases 'iqr:T' and 'range:T' to compute interquartile range
    and range.
   Keyword phrase 'excludeM:T' excludes the Median from the lower and
    upper halves of the data when computing quartiles and IQR
   Case is ignored in keyword names
 Change to print() and error()
   Keyword phrase 'zero:zeroString' prints CHARACTER scalar zeroString
    in place of zero for REAL variables
 Change to stemleaf() and boxplot()
   Keyword phrase 'excludeM:T' excludes the Median from the lower and
    upper halves of the data when computing quartiles; this also affects
    macro vboxplot()
 Changes to rotation()
   Keyword phrase 'method:"quartimax"' specifies quartimax rotation of
    factor loadings
   Keyword phrases 'method:"orthomax",lambda:lam' specifies orthomax
    rotation with parameter lam (lam = 1 is varimax, lam = 0 is
    quartimax)
 Changes to macro file Arima.mac
   You can modify the sign conventions of coefficients in ARIMA models.
    Type arimahelp(MASIGN) for details
   New macro() neg2logLarma for computing various quantities from data
    for specified values of ARMA or ARIMA parameters
   Improvements to macro arima(), including a new keyword 'mlecycles'
   Changes in choice of length of transforms (number of frequencies).
    If you don't specify, a length with no prime factors > 29 is
    selected; if you do specify using keyword 'nfreq' of variable 'S',
    it is an error if the number of frequencies has a prime factor > 29.
 Changes in macro file Tser.mac
   Macros ffplot() and tsplot() look for CHARACTER scalar TIMEUNIT to
    construct default labels and title.
 Changes to restore()
   New keyword phrase 'options:F' suppresses restoring option values
    saved in the workspace
   Variables DATAPATHS, DATAFILE, and MACROFILES are no longer restored
    if they already exist.  Non-restored values from the workspace file
    are made components of structure SAVEDNAMES from which they can be
    extracted if wanted
   On windowed versions, option 'matchdelay' is never restored when
    restoring a workspace saved on an incompatible computer
   New keyword phrase 'foreignok:T'allows an attempt to restore a
    binary workspace file written on an incompatible computer
   Enhancement so that restore() rearranges the byte order of the
    elements of variables saved on an incompatible computer
 Design.mac and Design.hlp have been updated
 Bug fixes
   Bug fix in determining value of a macro or compound command.  The
    value is now the value of the last expression even if it is followed
    by an empty line or a comment, in conformity with the documentation.
   Bug fix in rft(), hft() and cft() when length has more than 20 prime
    factors; another bug when the product of unpaired factors is too
    large has not been fixed but is shortcircuited, causing an error.
   Bug fix in glmfit() with dist:"binom"
   Bug fixes in help(), convolve(), svd(), eigen(), eigenvals(),
    releigen() and releigenvals()
   Bug fix in keyvalue(): keyword 'default' now works when the keyword
     property is 'macro' or 'graph'
   Bug fix in parsing <<"macroName">>(args).  Now macro files are
     searched if macroName is not defined.
   Several bug fixes in macro readdata()
@@@@______

====updates_412*#general
%%%%
Type help(updates_412) for a summary of changes made between the
  releases of Versions 4.12 and 4.13 of MacAnova.
%%%%
@@@@changes_between_versions_4.12_and_4.13
 Assignment to structure components specified by name and/or number is
   possible.  For example, when Str is a structure, Str$b <- x and
   Str$a$b <- x, Str[[J]] <- x, Str$a[[J]] <- x, and Str[[i]][[J]] <- x
   are all legal and do what they should.  When y is not a structure,
   y[[1]] <- x is the same as y <- x.
 You can embed '_' in numbers to improve readability.  For example,
   123_456.789_1e4 is the same as 123456.7891e4 (not read by read() or
   matread())
 Fortran style double precision numbers like -3.14592654d3 and 4.15D-5
   are now read as if the 'd' or 'D' were 'e' (not by read() or
   matread())
 Arguments to macros and certain functions are now checked for correct
   matching of '{' by '}', '[' by ']' and '(' by ')' before the macro or
   function is run
 New macro and variable attribute 'locked' protects them against casual
   change by deletion or assignment.
 New functions lockvars() and unlockvars() to lock and unlock variables.
 New function islocked() to determine whether a variable or macro is
   locked.
 New function getkeywords() to extract keywords from macro argument
   list.
 New functions digamma() and polygamma() to compute digamma function
   (derivative of log(gamma(x))) and its derivatives
 New function makesymbols() to generate custom plotting symbols.
 New functions pushmodel() and popmodel() allow use of GLM commands in
   macros without changing side effect variables or internal GLM
   information
 New macro buildfactor() in design.mac eases creation of factors for
   factorial data in standard order
 New predefined macro writedata() writes vector arguments as columns of
   data in a file or returns a CHARACTER scalar representation of
   such a file.
 New predefined macro clipwritedat() puts vector arguments as columns of
   data on the clipboard for pasting into a spread sheet or other
   document.
 New macro formatpval() in file MacAnova.mac for formatting P-values for
   printing
 New command line flag -savemodels N allows you to set default number of
   models that can be save using pushmodel()
 Enhancement of makecols()
   It prints a list of variables created, suppressable by silent:T
   New keyword 'factors' allows you to specify some or all of columns
   are factors
 Changes in order of arguments power() and power2(); previous order
   still works
 Change to nameof().  The names returned for a missing argument and a
   keyword phrase are "" and the keyword name, respectively.
 Change to makefactor().  When the vector argument is CHARACTER data, by
   default the values are attached as row labels to the result.
 Change to split().  It is now an error to have any factor with more
   than 32767 levels
 Change to solve(), rsolve(), det(), %/% and %\%.  It is now an error
   when overflow is detected. Keyword phrase quiet:T on solve() and
   rsolve() enables a warning message when singok:T is an argument
 Enhancements to boxplot()
   Keywords 'vs' and 'boxsize' allow you to plot boxes against a
   predictor variable and control the thickness of boxes Keyword
   'boxtype' allows a choice between two types of box plots
 Enhancements to sum(), prod(), max() and min()
   Keywords 'dimensions' and 'margins' allow you to operate over other
   dimensions than the first.  They make it easier to compute marginal
   totals, products and extremes from multidimensional tables
   'squeeze:T or F' controls whether dimensions operated over are
   squeezed out of the result
   'undefval:U' specifies U is the result when all values operated on
   are MISSING
   'silent:T' suppresses warning messages for MISSING values or overflow
 Enhancements to describe()
   Keyword phrase 'fivenum:T' computes the extremes and quartiles
   'silent:T' suppresses warning messages for MISSING values or overflow
 Enhancement to cumxxx() functions
   Functions cumbeta(), cumbin(), cumchi(), cumdunnet(), cumF(),
   cumgamma(), cumnor(), cumpoi(), cumstu() and cumstudrng() all
   recognize keyword phrase 'upper:T' and 'lower:F', both of which
   signal that upper tail probabilities should be computed instead of
   lower tail.  For some of these functions, cumxxx(x,...,upper:T)
   preserves accuracy lost due to cancellation by 1 - cumxxx(x,...).
 Enhancement to invxxx() functions
   Functions invbeta(), invchi(), invdunnet(), invF(), invgamma(),
   invnor(), invstu() and invstudrng() all recognize keyword phrase
   'upper:T' which signals that upper tail probability points should be
   computed instead of lower tail.  For some of these functions, when p
   is small, invxxx(p,...,upper:T) preserves accuraccy as compared to
   invxxx(1 - p, ...).
 New tabs() keyword phrase 'silent:T' suppresses warning messages for
   MISSING values or overflow.
 New swp() keyword phrase 'tolerance:Tol' allows more control over which
   columns will be 'swept'.
 New rotation() keyword phrase 'kaiser:T' specifies Kaiser normalization
   of factor loadings being rotated.
 New delete() keyword phrase 'lockedok:T' allows deleting locked
   variables.  Also 'return:F' is now legal on delete().
 New list() and listbrief() keyword phrase 'locked:T' restricts the
   items listed to locked variables and macros.
 New name line keyword LOCKED on files read by read(), matread() and
   macroread() specifies a variable or macro is to be locked
 Predefined variables PI, E and DEGPERRADIAN are now locked, as are
   certain pre-defined macros such as redo(), enter(), enterchars(), and
   breakif()
 New pre-defined locked variable NA, a REAL scalar with value MISSING
   allows usage like x <- vector(1,2,NA,3)
 New options
   After setoptions(quiet:T), all output except prompts and error
   messages is suppressed
   After setoptions(traceback:T), error messages in macros will print
   the chain of calling macros
   After setoptions(minpvalue:minp), where 0 <= minp <= .001, P-values
   smaller than minp are printed as "< 1e-08", say, when minp = 10^-8.
   Option 'enableitem' determines whether File Menu items Print Window
   and Print Graph are enabled in the Windows and Motif versions; they
   are disabled by default.
 Change in spool()
   New keyword phrase 'everything:T' forces all output to be spooled,
   even when output to the screen or windows has been suppressed by
   setoptions(quiet:T)
 Change in match()
   New keyword phrase 'ignorecase:T'
 Changes in help() and usage()
   Keyword phrase 'index:helpfilename' prints an annotated index of a
   help file; the names of the indices for the help files named in
   CHARACTER vector HELPFILES are in pre-defined CHARACTER vector
   HELPINDICES
   Macro addhelpfile() updates HELPINDICES as well as HELPFILES
   Macro names now have '()' appended in help and documentation
 Changes in readdata() and clipreaddata()
   File or path name "" now handled as you would expect in Windowed
   versions
   'sort:F' changes order factor levels are assigned to values of
   non-numerical column
 Changes in resvsindex(), resvsrankits(), and resvsyhat()
   Default plotting symbol is "\6" (drawn asterisk), not "*"
   Alternate symbols are specified by keyword 'symbols'
   Default values for 'title', 'xlab' and 'ylab' have changed
   They now work correctly after arima()
   New keyword phrases 'usehii:T' or 'usehii:F' affect how residuals are
   standardized
   New keyword phrase 'standres:F' suppresses standardization
 Fixed some bugs in arima(), added a new side effect variable AICC and
   tinkered with printed output
 Fixed bug in model parser so new {...} variables are always entered in
   model
 Fixed bug in getfilename() in Windows and Motif versions
@@@@______

====updates_413*#general
%%%%
Type help(updates_413) for a summary of changes made between the
  releases of Versions 4.13 and 4.14 of MacAnova.
%%%%
@@@@changes_between_versions_4.13_and_4.14
 New function lowess() to smoother scatterplots using the LOWESS
   algorithm
 New function equal() to test the equality of two variables of any type
   except GRAPH
 New functions type() and shapeof() return the types and shapes of their
   arguments as CHARACTER scalars or vectors.
 New functions cdivc(), cdivcj(), hdivh() and hdivhj() to compute ratios
   of fully complex or packed Hermitian series.
 New macros cdiag(), ceigen(), cjtranspose(), cmatmultc(), csolve(),
   csubscr(), ctrace(), and ctranspose() for working with complex
   matrices in fully complex form
 New macro printoptions() to print option values in concise format
 New macro restorenames() to restore file and path names saved in
   structure SAVEDNAMES by restore()
 New usage tsplot(y,time ...), where time is a vector of increasing time
   points plots time series defined at possibly non equally spaced
   times.
 When x is a scalar, array(x, dims ...) is equivalent to array(rep(x,N),
   dims ...) where N = product of dimensions.
 list() output now indicates which variables have labels and/or notes.
   Keyword phrases labeled:T and notes:T specify that those only
   variables with labels and/or notes are to be listed.
 Keyword 'symbols' on boxplot() and vboxplot() controls what symbols are
   used for outliers.
 Improved default tick marks with 'logx:T' and/or 'logy:T' on all
   plotting commands
 Subtopics in help files can now have associated titles that are used to
   provide better help() output.
====updates_old*#general
%%%%
Type help(updates_old) for a summary of changes made prior to the
  release of Version 3.35.
%%%%
@@@@changes_prior_to_version_3.35
             Summary of changes made prior to Version 3.35

2.0 -> 2.1
 New functions acos(), asin(), ceiling(), chplot(), colplot(), eigen(),
   floor(), halfnorm(), lgamma(), rank(), releigen(), rowplot(),
   secoefs(), sqrt(), t(), and tabs()
 contrast() now computes the estimated contrast
 coefs() now computes all coefficients if no argument used
 Minor changes in logistic(), poisson(), and robust()

2.1 -> 2.2
 Numerous bug fixes (contrast(), secoefs(), plot(), colplot(), and
   rowplot())
 New functions cor(), and tquant()

2.2 -> 2.21
 Bug fix in eigen()

2.21 -> 2.3
 Bug fixes in fastanova(),cumstu(), and cumF()
 New functions invnor(), invstu(), invF(), and invchi()
 Function tquant() removed (replaced by invstu())
 New algorithm for random number generation

2.3 -> 2.4
 Bug fix in invstu(). New function asciisave()

2.4 -> 3.0
 Major changes. See topic 'macanova3'.

3.0 -> 3.1
 New plotting commands, PostScript output, improved memory management

3.1 -> 3.2
 Many operations, including transformation and arithmetic operate on
   structures as well as scalars, vectors, matrices, or arrays
 Subscripts can also be used on structures

3.2 -> 3.3
 Number of variables in GLMs (generalized linear or linear models
   increased to 95
 Improved workspace file format
 New functions modelinfo() and xvariables() for getting information
   about linear models, in particular for computing the basis vectors
   used by MacAnova
 Many new functions, including cholesky(), partacf(), yulewalker(),
    polyroot(), and bin()

3.3 -> 3.31
 Bug fixes
 New arithmetic assignment operators <-+, <--, <-/, <-^, and <-%%
 Most recent command typed saved as macro LASTLINE

3.31 -> 3.32
 Enhanced modelinfo()
 New ASCII workspace file format with no non-printable characters

3.32 -> 3.33
 New option batchecho
 Expansion of '~' in file names. See topic 'files'
 Greater format control in paste()
 delete(real:T) and other similar usage allowed
 Enhanced coefs(), secoefs(), putascii(), swp()
 Enhanced hprdh(), hprdhj(), cprdc(), cprdcj()
 Enhanced listbrief(), sum(), prod(), min(), max()
 Enhanced cluster()
 New function inforead()
 Various bug fixes

3.33 -> 3.34
 ==, !=, <=, >=, >, < work with LOGICAL data
 Input data to cluster() standardized by default
 Keywords linetype and thickness on some plotting commands
 Can specify a dot as a plotting symbol
 Enhancement to parsing of macro arguments that are quoted strings
 Improved parsing of models to catch some probable errors
 screen() output, including models selected, can be kept
 Operations for manipulating bit structure of integers (type
   'help(bit_ops)')
 Enhancements to modelinfo()
 Improved Undo on Macintosh version
 Various bug fixes

3.34 -> 3.35
 getoptions(nsig:T, format:T), for example, made legal
 help(key:"foo") lists topic names assciated with "foo"
 New keyword phrase coefs:F on most glm commands
 reverse(x) reverses ordering of rows of matrix x
 rotation(loadings) does varimax rotation
 Revised versions of readcols() and makecols() macros
 anova() detects and takes advantage of balanced main effect designs
   such as Latin squares
 New keywords means, vars, counts on tabs()
 New keyword quiet on getseeds() and setseeds()
 New option 'update'
 New extended memory protected mode DOS version allows much larger
   variables
 Enhanced Macintosh interface, including multiple output windows,
   non-interactive mode, recognition of function keys on extended
   keyboard, more accurate computation of the number of lines per page
   when printing, and matching of parentheses and brackets
 Minor changes to run() to round when very close to zero or the ending
   value
 Better use of memory by some functions
 Various bug fixes
@@@@______

====usage()#general
%%%%
usage(Topic [,allfiles:T]), topic a quoted or unquoted name of a help
  topic
usage(Topic1, Topic2, ... [,allfiles:F])
%%%%
@@@@usage#Usage
usage(Topic) gives short usage information on Topic, where Topic is a
function or command or one of the general information topics such as
'options' or 'graph_keys'.

usage() works identically to help(), except it gives only a brief
summary of the topic, instead of all the detail.

usage() returns an "invisible" LOGICAL scalar whose value is True only
when at least one topic requested was found.  The value may be assigned
or tested but will not be printed automatically.  See topic
'variables:"invisible"'.

usage() scans the files NAMED in CHARACTER vector HELPFILES.  If the
current help file is not named in HELPFILES, it is scanned first.

If there is only one topic (the usual case), usage() scans files until
it finds the topic.  You can use 'allfiles:T' as an argument to force it
to search all the files in HELPFILES.

usage(topic1, topic2, ...) does the same except that all the files are
searched for the topics.  When you use 'allfiles:F' as an argument, no
additional files are searched once a topic has been found in a file.

For many commands and macros, help(topic, subtopic:"usage") provides
more complete usage information than does usage().

usage() is implemented as a macro which uses gethelp() and getusage() to
retrieve the information.  Functions getusage() and gethelp() scan only
a single file.

@@@@history_note#History note
Prior to Version 4.12, getusage() was named usage() and there was no
macro named usage().

@@@@see_also#Cross references
See help(), getusage() and gethelp() for full details.  See topic
addhelpfile() for information on adding file names to HELPFILES.
@@@@______

====User()*#general,control,files
%%%%
User(funName [,resource:resName][,control keyword phrases],arg1 [,...]),
  funName and resName CHARACTER scalars; control keyword phrases are any
  of callback:T, symbols:T, pointers:T and quiet:T; arg1, ... arguments
  to a user function; if argument is keyword phrase other than
  'protect:arg', it is returned, possibly modified.
%%%%
@@@@get_help_with_userfunhelp
Help on User() is in file userfun.hlp.  You can retrieve the help by

  Cmd> userfunhelp(User)

It provides a complete description of User() which you use to run an
externally compiled user function.

  Cmd> userfunhelp()
gives you a complete list of topics related to user functions.
@@@@______

====userfunhelp()#general
%%%%
userhelp(topic1 [, topic2 ...] [,usage:T] [,scrollback:T])
userhelp(topic, subtopic:Subtopics), CHARACTER scalar or vector
  Subtopics
userhelp(topic1:Subtopics1 [,topic2:Subtopics2 ...])
userhelp(key:Key), CHARACTER scalar Key
userhelp(index:T [,scrollback:T])
%%%%
@@@@usage#Usage
userfunhelp(Topic1 [, Topic2, ...]) prints help on topics Topic1,
Topic2, ... related to user functions.  The help is taken from file
userfun.mac.

userfunhelp(Topic1 [, Topic2, ...] , usage:T) prints usage information
related to these topics.

userfunhelp(index:T) or simply userfunhelp() prints an index of the
topics available using userfunhelp().  Alternatively
help(index:"userfun.hlp") does the same thing.

userfunhelp(Topic, subtopic:Subtopic), where Subtopic is a CHARACTER
scalar or vector, prints subtopics of topic Topic.  With subtopic:"?", a
list of subtopics is printed.

userfunhelp(Topic1:Subtopics1 [,Topic2:Subtopics2], ...), where
Suptopics1 and Subtopics2 are CHARACTER scalars or vectors, prints the
specified subtopics.  You can't use any other keywords with this usage.

In all the first 4 of these usages, you can also include help() keyword
phrase 'scrollback:T' as an argument to userfunhelp().  In windowed
versions, this directs the output/command window will be automatically
scrolled back to the start of the help output.

@@@@key_keyword#Keyword 'key'
userfunhelp(key:key) where key is a quoted string or CHARACTER scalar
lists all topics cross referenced under Key.  userfunhelp(key:"?")
prints a list of available cross reference keys for topics in the file.

userfunhelp() is implemented as a predefined macro.

@@@@see_also#Cross references
See help() for information on direct use of help() to retrieve
information from userfun.hlp.
@@@@______

====user_fun%#general,control,files
%%%%
Type userfunhelp(user_fun) for information on the structure of user
  functions.
Type userfunhelp(callback_fun) for information on the structure of user
  functions making "call backs" to MacAnova.
Type userfunhelp(arginfo_fun) for information on how to enable automatic
  checking of arguments to a user function.
%%%%
@@@@get_help_with_userfunhelp
This topic is now in file userfun.hlp.  Type
  userfunhelp(user_fun)

It provides a brief introduction to the form of a user function (routine
compiled separately from MacAnova) that can be loaded by loadUser() and
executed by User().

Some other useful entries in userfun.hlp are callback_fun and
arginfo_fun.  Type
  userfunhelp()
for a complete list of entries.
@@@@______

====variables%#syntax,variables,character variables,logical variables,null variables
%%%%
Type help(variables) for details about (1) names of permanent and
  temporary variables, (2) types of variables, (3) invisible variables,
  (4) locked variables and (5) coordinate labels.
%%%%
@@@@variables_and_their_names#Variables and their names
Data are stored in named "variables" with names up to 12 characters
long.

Names are case sensitive (for example, 'residuals' is a different name
from 'Residuals').  You should avoid names in all capital letters (for
example 'RESIDUALS') because MacAnova uses some such names for special
purposes.

You should normally select names that are relevant to the problem such
as 'weight', 'residuals', or 'depv'.

Variables can be permanent (the variable remains accessible until you
delete it) or temporary (the variable is automatically deleted at the
next prompt).  Temporary variables are particularly useful in macros.
See topics macro() and 'macros'.

@@@@permanent_variables#Permanent variables
Permanent variables have names that begin with a letter (a-z or A-Z) or
the character '_', followed by 0 or more letters, numerals or '_'.  For
example 'x12a' and 'time_of_day' are names of permanent variables.  The
use of variable names that start with '_' can lead to confusion since
the variable is then "invisible" (see below).

@@@@temporary_variables#Temporary variables
Temporary variables have names that start with '@' followed by a letter
or '_' and 0 or more letters, numerals or '_'.  Examples are '@x1a' and
'@_Result.  A variable whose name starts with '@_' is "invisible".  All
temporary variables are automatically deleted each time a prompt is
printed.

@@@@invisible_variables#Invisible variables
"Invisible" variables have names that begin with '_' or '@_'.  They
differ from "visible" variables in two ways.  (i) Commands list() and
listbrief() ignore invisible variables unless 'invis:T' is an argument
(see listbrief(), list()); and (ii) typing an invisible variable's name
does not result in the variable's value being printed.

@@@@special_variables#Special variables
A few variables are "special" and have non-standard properties.
Currently CLIPBOARD, GRAPHWINDOWS and SELECTION (GTK only) are the
only "special" variables.  See topics 'CLIPBOARD' and 'GRAPHWINDOWS' for
details.

@@@@locked_variables#Locked variables
Locked variables are variables that cannot be deleted or assigned to.
You can mark variables as being 'locked' using lockvars().  You can
unlock locked variables using unlockvars() and delete them using keyword
phrase 'lockedok:T' on delete().

When you save your workspace (see save()), the locked status of each
variable is retained so that when you restore the workspace (see
restore()) a locked variable is still locked.  However, locking a
variable does not protect it from being destroyed by restore().

One situation when locking a variable might be helpful is when you have
computed a valuable result that took a long time and you want to make
sure you don't destroy it accidentally.

You cannot lock temporary variables or "special" variables.

@@@@variable_types
                           Types of Variables
There are several types of variables, including REAL, LOGICAL,
CHARACTER, GRAPH, STRUCTURE, MACRO and NULL.  In certain output,
LOGICAL, CHARACTER, and STRUCTURE are abbreviated as LOGIC, CHAR, and
STRUC, respectively.

Variables of type LONG can be created by asLong() but they exist only
transiently, being "coerced" to equivalent REAL variables when assigned.
See asLong().

A REAL variable contains numerical data or the special value MISSING.  A
LOGICAL variable contains data with values limited to True, False or
MISSING (see 'logic').  A CHARACTER variable contains data consisting of
character information.  A LONG variable contains integer values between
-2147483647 and +2147483647 = 2^31 - 1.

REAL, LOGICAL, CHARACTER or LONG variables may be scalars (consist of a
single data item; see 'scalars'), vectors (several data items indexed by
a single subscript; see 'vectors'), matrices (data items indexed by two
subscripts; see 'matrices'), or arrays (data items indexed by more than
two subscripts; see 'arrays').  See also topic 'subscripts'.

A GRAPH variable encapsulates all the information needed to draw a
graph.  See topic 'graphs'.

A STRUCTURE variable or simply a structure consists of named components
of data which may be of any type, including STRUCTURE.  See topic
'structures'.

A MACRO variable or simply a macro contains one or more MacAnova
commands to be executed together.  See topics 'macros', 'macro_syntax',
macro().

A NULL variable contains no data of any sort.  See topic 'NULL'.

You can attach descriptive notes to variables, including GRAPH variables
and macros.  See topics 'notes', attachnotes(), appendnotes(),
getnotes(), and hasnotes().

@@@@coordinate_labels
                           Coordinate Labels
REAL, LOGICAL and CHARACTER variables may have vectors of labels for
each coordinate.  In particular matrices may have row and column labels.
A structure may have labels for each component.  Labels propagate
through operations and functions in a fairly sensible way.  Labels are
primarily used in output .  See topic 'labels' for details.
@@@@______

====varnames()#variables,glm,character variables
%%%%
varnames(Model [,stripat:T,stripbrack:T]) where Model is CHARACTER
  scalar containing a GLM model
varnames([stripat:T,stripbrack:T]) is equivalent to varnames(STRMODEL
  [,stripat:T,stripbrack:T])
%%%%
@@@@usage#Usage
varnames(Model) returns as a CHARACTER vector the name of the response
variable followed by the names of the factors and variates in Model in
the order they first appear.  Model should be a CHARACTER variable or
quoted string.

Model must contain a legal GLM model, except that variables in the model
need not be REAL or even be defined.  Variables to evaluated "on the
fly" are not evaluated and the expression is returned as the name
enclosed in {...}.  See topic 'models'.

NOTE: This represents a change from earlier versions.  Previously
varnames(Model) extracted the variable names without checking the
validity of the model and did not handle expressions to be evaluated on
the fly correctly.

varnames(Model, stripbrack:T) does the same, except any names which are
expressions are not enclosed in {...}.

varnames(Model, stripat:T [,stripbrack:T]) does the same, except any
non-expression names which are temporary variables have the leading '@'
strippped off.

@@@@no_model_specified#No model specified
varnames([keyword phrases]) without a model is equivalent to
varnames(STRMODEL [,keyword phrases]), returning a vector of the names
of the variables in STRMODEL.  This is usually the model used by the
most recent GLM (generalized linear or linear model) command such as
regress(), anova(), or poisson().

@@@@examples#Examples
  Cmd> varnames("{log(y)} = @x + {@x^2}")
  (1) "{log(y)}"
  (2) "@x"
  (3) "{@x^2}"

  Cmd> varnames("{log(y)} = @x + {@x^2}",stripat:T)
  (1) "{log(y)}"
  (2) "x"
  (3) "{@x^2}"

  Cmd> varnames("{log(y)} = @x + {@x^2}",stripbrack:T)
  (1) "log(y)"
  (2) "@x"
  (3) "@x^2"

  Cmd> varnames("{log(y)} = @x + {@x^2}",stripbrack:T,stripat:T)
  (1) "log(y)"
  (2) "x"
  (3) "@x^2"

@@@@see_also#Cross references
See also topics xvariables(), modelvars(), 'models', compnames(),
nameof(), 'glm'.
@@@@______

====vboxplot()#plotting,descriptive statistics
%%%%
vboxplot(x1,x2,...,xk [,vs:indv, boxsize:W] [,excludeM:T, boxtype:m,
  symbols:outlierSyms, graphics keyword phrases]), x1,...,xk REAL
  vectors, indv REAL length k vector with no MISSING values, m > 0
  integer, W REAL non-negative vector or scalar, outlierSyms CHARACTER
  scalar or vector of length 2
vboxplot(Struc, [,vs:indv, boxsize:W] [,excludeM:T, boxtype:m,
  symbols:outlierSyms, graphics keyword phrases]), Struc a structure
  with k REAL vector components
%%%%
@@@@usage#Usage
vboxplot(var1, var2, ... , vark [,graphics keyword phrases]) produces
vertically oriented parallel Tukey boxplots for the vectors var1 through
vark.  It is identical with boxplot(var1, var2, ..., vark, vertical:T
[,graphics keyword phrases]).

vboxplot(Struc [,graphics keyword phrases]) produces vertically oriented
parallel box plots for the components of structure Struc, all of which
must be vectors.  It is identical with boxplot(Struct, vertical:T
[,graphics keyword phrases]).

You can use all the graphics keyword phrases that boxplot() recognizes.
Keyword 'symbols' is interpreted differently from other plotting
commands; see below.

@@@@symbols_keyword#Keyword 'symbols'
Keyword 'symbols' has a different meaning from other plotting commands.
You use it to specify symbols for moderate outliers (beyond inner fences
and inside outer fences) and extreme outliers (beyond outer fences).
The value of 'symbols' must be a CHARACTER scalar or vector of length 2.

  Cmd> vboxplot(x1, x2, x3, symbols:vector("\3", "\5"))

uses "\3" (square) as a symbol for moderate outliers and "\5" (triangle)
as a symbol for extreme outliers.  When the value of 'symbols' is a
scalar, the default symbol is used for extreme outliers.

@@@@see_also#Cross references
For more information including how to use split() to create a structure
argument, see boxplot().
@@@@______

====vconcat()#combining variables,variables,null variables
%%%%
vconcat(a,b,c,... [,labels:structure(rowLabs,colLabs), silent:T]) where
  a, b, c, ... matrices and rowLabs and colLabs are CHARACTER scalars or
  vectors
%%%%
@@@@usage#Usage
vconcat(a,b,c,...) combines matrices a, b, c ... vertically by
concatenating their columns.

All arguments must be of the same type, REAL, LOGICAL, or CHARACTER, and
have the same number of columns n.  The result is a matrix of that type
with n columns and ma+mb+mc+... rows, where ma, mb, mc, ... are the
number of rows of a, b, c, ... .

vconcat(a,b,...,labels:structure(rowLabs,colLabs) [,silent:T]) uses
CHARACTER scalars or vectors rowLabs and colLabs as row and column
labels for the result.  With silent:T, no warning is printed if labels
are the wrong size.  See topic 'labels' for details.

@@@@non_matrix_arguments#Non matrix arguments
Any argument that is a vector of length m is considered to be a m by 1
matrix.  In particular, if a is a vector of length m, vconcat(a) is a m
by 1 matrix.

An argument that is an array with only two dimensions not equal to 1 is
considered to be a matrix (see 'matrices').  For example,
   vconcat(array(run(6),1,3,2),array(run(7,14),4,1,2))
is equivalent to
   vconcat(matrix(run(6),3),matrix(run(7,14),4))

Any argument of type NULL is ignored.  When all arguments are NULL, so
is the result.

@@@@see_also#Cross references
See also topics hconcat(), 'matrices', 'vectors'.
@@@@______

====vecread()#input,files
%%%%
vecread(FileName [keyword phrases]), FileName a CHARACTER scalar, (REAL
  data)
vecread(FileName, bywords:T [keyword phrases]) (CHARACTER data)
vecread(FileName, bylines:T [keyword phrases]) (CHARACTER data)
vecread(FileName, bychars:T [keyword phrases]) (CHARACTER data)
Keyword phrases are: silent:T, quiet:F, echo:F or echo:T, prompt:F,
  printname:F, badkeyok:T, nofileok:T, stop:stopChar or go:goChar,
  skip:skipChar, skipthru:skipthruChar, n:N, startline:M, bypass:P,
  badvalue:val, byfields:T, stopChar, goChar, skipChar CHARACTER scalars
  consisting of one character, N > 0, M > 0, P >= 0 integers, val a REAL
  scalar or MISSING.  See topic 'vecread_keys'.
FileName can also be CONSOLE or have the form string:charVal where
charVal is a CHARACTER scalar or vector.
%%%%
@@@@introduction#Introduction
This topic has sections on Reading REAL data, with examples, Reading
CHARACTER data, with examples, Reading a matrix with vecread(),
Controlling the lines to be read, Reading from a CHARACTER variable, and
Reading the console or batch file.

Topics 'vecread_file' and 'vecread_keys' provide additional information
on file format and keyword use for vecread().

vecread() reads data from a text file sequentially, row by row, starting
at the beginning of the file, interpreting items as numerical or
character data depending on keyword phrases.

@@@@general_usage#General usage
The general usage of vecread() is

  Cmd> Var <- vecread(FileName [,keyword phrases])

where FileName is a quoted string or a CHARACTER variable.  In windowed
versions, when FileName is "", you are prompted to enter the file name
using a dialog box.  Var becomes a REAL or CHARACTER vector or possibly
(with 'nofileok:T') NULL.

@@@@controlling_first_line_read#Controlling the first line read
vecread(FileName [,keyword phrases], bypass:P), where P > 0 is an
integer, skips by all lines until P lines starting with the "stop
character" (default '!'; see below) have been read.  bypass:P can be
used with any other keyword phrases.  Other keywords affecting which
lines are read have no effect until after the P-th line starting with
the stop character.  This allows you to have several data sets in the
same file, separated by lines starting with the stop character.

vecread(FileName [,keyword phrases], startline:M), where M > 0 is an
integer, completely ignores the first M-1 lines in the file (or after
the P-th line starting with the stop character with 'bypass:P').
startline:M can be used with any other keyword phrases.

@@@@reading_real_data
                           Reading REAL data
vecread(FileName) and vecread(FileName, byfields:T) read numbers from
the file with name FileName and return a REAL vector containing the
data.

Data of the form '?', '??', '???', ... as well as an isolated 'NA',
period '.'  or asterisk '*' are read as MISSING.

A number that is too large to be represented in the computer (for
example, -3.1e10000) is read as MISSING.

@@@@byfields_keyword#Keyword 'byfields'
Reading REAL data without byfields:T or with byfields:F
 The file should contain a sequence of numbers or missing value codes,
 separated by tabs, spaces or single commas.

 Unreadable items are skipped and an informative message is printed
 once.  Numbers are extracted from "words" like '-1.2a5' which is
 interpreted as if it were '-1.2 a 5'.  Single commas between items are
 ignored; a sequence of m commas is treated as m-1 unreadable items.

Reading REAL data with byfields:T
 The file is interpreted as a sequence of possible empty "fields"
 separated by commas, spaces, tabs and ends of lines, with each field
 becoming an element of the result.  A field that is not a number or
 missing value code is unreadable and is returned as MISSING.  This
 includes fields like '-1.2a5' that contain one or more digits.  Empty
 fields, before a leading comma, after a trailing comma and between two
 commas with no intervening visible characters, are returned as MISSING.

@@@@badvalue_keyword#Keyword 'badvalue'
vecread(FileName, badvalue:BadVal [,byfields:T]), where BadVal is a REAL
scalar or MISSING (?), returns a REAL vector with BadVal substituted for
every unreadable item.  For example, when reading '-1.2a5 17 ?',
vecread(FileName, badvalue:-99) returns vector(-1.2,-99,5,17,?) and
vecread(FileName, byfields:T, badvalue:-99) returns vector(-99,17,?).
With byfields:T this enables you to distinguish between codes for
MISSING and non-numeric items.

@@@@examples_of_REAL_data
                       Reading REAL data examples
File "data1.txt" looks like the following:
   Henry   Male   67.3,10.5
   Susan   Female 59.2,   ?

File "data2.txt" looks like the following (note the extra comma):
   Henry   Male   67.3,   10.5
   Susan   Female 59.2,  ,   ?

File "data3.txt" looks like the following (note digits in fields):
   Henry   Season_1 67.3,10.5
   Susan   Season_2 59.2,   ?

  vecread("data1.txt") returns vector(67.3,10.5,59.2,?).

  vecread("data1.txt",byfields:T) returns vector(?,?,67.3,10.5,?,?,59.2,
   ?).

  Both vecread("data1.txt", badvalue:-1) and vecread("data1.txt",
   badvalue:-1,byfields:T) return vector(-1,-1,67.3, 10.5,-1,-1,59.2,?).

  vecread("data2.txt", badvalue:-1) returns vector(-1,-1,67.3,10.5,-1,
   -1,59.2,-1,?).

  vecread("data2.txt", badvalue:-1,byfields:T) returns
   vector(-1,-1,67.3, 10.5,-1,-1, 59.2,?,?).

  vecread("data3.txt") returns vector(1,67.3,10.5,2,59.2,?), extracting
   1 and 2 from Season_1 and Season_2.

  vecread("data3.txt",badvalue:-1) returns vector(-1,-1,1,67.3,10.5,-1,
   -1,2,59.2,?).

  vecread("data3.txt",byfields:T) returns vector(?,?,67.3,10.5,?,?,59.2,
   ?), treating Season_1 and Season_2 as unreadable.

  vecread("data3.txt", byfields:T, badvalue:-1) returns
   vector(-1,-1,67.3, 10.5,-1,-1,59.2,?).

  vecread(string:",1,,2,3,",byfields:T) returns vector(?,1,?,2,3,?)
   (see topic 'vecread_keys' for the use of 'string').

@@@@reading_CHARACTER_data
                         Reading CHARACTER data
vecread(fileName, bywords:T), vecread(fileName, bylines:T) and
vecread(fileName, bychars:T) read CHARACTER data from a file.  The
latter two can read data containing commas, spaces or tabs or other
"invisible" characters.

@@@@bywords_keyword#Keyword 'bywords'
vecread(FileName, bywords:T) returns a CHARACTER vector, each element of
which is a "word" from the file.  For this usage, a word is a sequence
of printable non-blank characters, excluding commas.  Words are
separated by commas, or spaces, tabs or other "invisible" characters.

Quotation marks (") are not special and are treated as any other visible
character that is not a comma.

An "empty" word, before a leading comma, after a trailing comma, or
between successive commas with no intervening visible characters, is
returned as the null string "".

@@@@bylines_keyword#Keyword 'bylines'
vecread(fileName, bylines:T) returns a CHARACTER vector, each element of
which is an entire line read from file fileName. The lines do not
include an end-of-line character but do include any other "invisible"
or non-printing characters such as TABS.

@@@@bychars_keyword#Keyword 'bychars'
vecread(fileName, bychars:T) returns a CHARACTER vector, each element of
which is a single character read from file fileName, including any
end-of-line characters (returned as "\n") or other invisible characters.

@@@@examples_of_CHARACTER_data
                    Reading CHARACTER data examples
Here are more examples of reading the sample files used above to
illustrate reading REAL data:

  vecread("data1.txt", bywords:T) returns vector("Henry","Male",
   "67.3","10.5","Susan","Female","59.2","?").

  vecread("data2.txt", bywords:T) returns vector("Henry","Male",
   "67.3","10.5","Susan","Female","59.2","","?").

  vecread("data1.txt", bylines:T) returns
   vector("Henry   Male   67.3,10.5", "Susan   Female 59.2,   ?").

  vecread("data1.txt",bychars:T) returns vector("H","e","n","r","y"," ",
   " "," ","M","a","l","e"," "," "," ", "6","7",".","3",",","1","0",".",
   "5","\n","S","u","s","a","n"," "," ", " ","F","e","m","a","l","e","
   ", "5","9",".","2",","," "," "," ","?", "\n")

  vecread(string:",,a,b,", bywords:T) returns vector("","","a","b","")
    (see below for the use of 'string').

The following creates macro isnumber that tests whether each "word" of
a CHARACTER scalar or vector represents a valid number:

  Cmd> isnumber <- macro("@tmp <-  paste(vecread(string:$1,bywords:T))
    !ismissing(vecread(string:@tmp,badvalue:?,byfields:T))",\
    dollars:T)

Then
  isnumber("3.45") returns True, isnumber("3b45") returns False, and
  isnumber("3.4 4.5 A") returns vector(T,T,F).

@@@@reading_matrix_with_vecread
                    Reading a matrix with vecread()
When the file contains a data matrix consisting of n rows of data, each
of k items, you can read the data into a n by k matrix by
  Cmd> x <- matrix(vecread(FileName [,byfields:T]),k)'
or, for CHARACTER data,
  Cmd> x <- matrix(vecread(FileName, bywords:T),k)'

The transpose is needed because vecread() reads row by row, but matrices
are filled column by column.

If there are several matrices in a file, separated by lines starting
with the stop character (default "!"), you can read the third one, say,
by
  Cmd> x <- matrix(vecread(FileName, bypass:2), k)'

@@@@controlling_which_lines_are_read
                     Controlling the lines to read
In addition to 'bypass:P' and 'startline:M', keyword phrases 'skip:C',
'skipthru:C', 'stop:C' and 'go:C' control which lines will be scanned
for data.  In each case C is a single character such as "#" or "!" .
These are referred to as the "skip character", the "skipthru character",
the "stop character" and the "go character".  Except for the stop
character, these have no effect until after the lines skipped by
bypass:P and startline:M.

The default stop character is "!", whether reading numerical or
CHARACTER data.  That is, a '!' terminates scanning the file.  There are
no defaults for the skip, skipthru or go characters.

Briefly, lines starting with the skip character are skipped, as are all
lines up to and including the first line starting with the skipthru
character, and reading is terminated by the stop character or a line
that does not start with the go character.  When the skipthru character
is "\n", reading will start after the first completely empty line.  See
topic 'vecread_keys' for details.

If '!' appears in the file as other than a stop character, you should
use 'stop:C', where C is a character that does not occur in the file.
If the file consists solely of standard ASCII characters, 'stop:"\377"'
is a good choice.

With 'bylines:T' and 'bychars:T' and when skipping lines as controlled
by 'bypass:P', the stop character is recognized only as the first
character in a line.  With 'bywords:T' or 'byfields:T' it is recognized
only as the first character in a word or field.  Otherwise it is
recognized at any position in a line.

When you use keyword phrase n:N (see above), reading is terminated when
N items have been read.  When a stop character is found or a line that
does not start with the go character is found before N items have been
read, reading is stopped and a warning message is printed.

@@@@reading_from_character_variable
                  "Reading" from a CHARACTER variable
vecread(string:CharVar [, keywords]) where CharVar is a CHARACTER scalar
or vector, does not read from a file.  Instead, it "reads" CharVar as if
were a file.  See topic 'vecread_keys' for details.

Here is a particularly useful way to use keyword 'string':

  Cmd> x <- vecread(string:CLIPBOARD [,byfields:T])
and
  Cmd> x <- vecread(string:CLIPBOARD,bywords:T)

would read data from the special variable CLIPBOARD.  In windowed
versions, this would be taken from the Clipboard.  Pre-defined macro
fromclip() makes use of this feature to read data on the Clipboard.  In
the GTK version, you can use special variable SELECTION in a similar way
to read the current X selection.  See topic 'CLIPBOARD'.

@@@@reading_from_console_or_batch_file
                Reading from the keyboard or batch file
vecread(CONSOLE [,keywords]) reads what you type rather than a file.  If
a variable CONSOLE exists, its value is ignored.  In windowed versions,
a dialog box is displayed in which you enter data; in other versions,
you are prompted to type in the data.  The prompt can be suppressed by
'prompt:F'.

Data should be typed in one of the formats just described.  To stop
input, type the stop character (default '!'), followed by RETURN, or, if
you provided a go character (see 'vecread_keys'), type a line starting
with any other character.  In windowed versions, clicking on the "Done"
or "Cancel" button in the dialog box also ends input.

In a batch file vecread(CONSOLE [,...]) reads the immediately following
lines as the data file.  For this usage it is essential that either a
stop character terminates the data or keyword phrase n:N limits
number of items read.  You will probably want to use 'prompt:F' in this
case.  See also batch().

@@@@other_keywords
        Other optional keywords phrases that may always be used
You can also specify the file name by 'file:FileName', which need not be
the first argument.  In addition, you can replace FileName by
'string:CharVar', where CharVar is a CHARACTER scalar or vector which is
"read" as if it were a file.

You can use keyword phrases 'echo:T', 'quiet:T', 'quiet:F', 'silent:T'
and 'printname:F' to control what vecread() prints.

You can ignore duplicated or unrecognized keywords by 'badkeyok:T'.
This is useful in writing macros, since you can have a line like
  @x <- vecread(string:@lines, stop:"$", badkeyok:T, $K)
without checking to see whether 'string', 'stop' or a non-vecread
keyword is a macro argument and thus included when $K is expanded.  See
topics 'macros' and 'macro_syntax'.

Keyword phrase 'nofileok:T' instructs vecread() to return NULL instead
of aborting when it is unable to open a file.  This is useful in writing
robust macros that use vecread().

See topic 'vecread_keys' for details on these keywords.

@@@@see_also#Cross references
See also topics readcols(), read(), matread(), macroread(), batch(),
'vecread_file', 'vecread_keys', 'files', console(), 'vectors'.
@@@@______

====vecread_file%#variables,files,input,output
%%%%
Type 'help(vecread_file)' for information on the format of files
to be read by vecread() and readcols()
%%%%
@@@@introduction#Introduction
This topic discusses the format of files vecread(), readcols() and
readdata() can read.  Such files are plain text files which contain only
REAL or CHARACTER data in unstructured format.

Macro readcols() uses vecread() to read a file.  The only difference in
file format is that, when no variable names are provided to readcols()
or readdata(), the first line of the file is interpreted as containing
variable names.

See topic 'matread_file' for information on the format of files to be
read by matread() and read().

See topic 'vecread_keys' for information on vecread() keywords.

@@@@multiple_data_sets_in_file#Multiple data sets in file
With the help of keyword 'bypass' you can read one of several sets of
data in the same file if the data sets are separated with lines
beginning with the "stop character" (default "!"; see 'vecread_keys').
You can read the third set, say, by including 'bypass:2' as an argument
to vecread() or readcols().  This discussion really describes the lines
after the bypassed data.

Keyword 'bypass' cannot be used with readdata().

@@@@REAL_data_in_file#REAL data in file
REAL data to be read by vecread(), readcols() and readdata() consist of
numbers and codes for MISSING, often on several lines.  When there are
several data items on a line, they are separated by spaces, tabs or
commas.  Any of '?', '.', '*' and 'NA' code for MISSING.  '??', '???',
... are treated as a single missing value.

Interpretation of extra commas and non-numeric "fields" (sequences of
characters that are not commas, spaces or tabs) depends on whether
'byfields:T' is an argument to vecread() or readcols().  See topic
'vecread_keys' for details.

readdata() always uses 'byfields:T' in reading REAL data,.

What is done with items that are not numbers or missing value codes
depends on whether 'badvalue:badv' is an argument to vecread(),
readcols() or readdata(), where badv is a REAL scalar or MISSING.  See
topic 'vecread_keys'.

@@@@CHARACTER_data_in_file#CHARACTER data in file
CHARACTER data to be read by vecread() or readcols() have no special
format when 'bylines:T' or 'bychars:T' is an argument.  When 'bywords:T'
is an argument, the file is interpreted as consisting of "words"
separated by "white space" or commas.  A word is a sequence of visible
characters other than commas.  An empty word, read as "", is assumed
before a leading comma, after a trailing comma or between two commas
enclosing no visible characters.

When all the data lines are at the start of the file and start with the
same character, for example '%', you can restrict reading to them by
including 'go:"%"' as an argument to vecread() or readcols().

Since keywords 'bywords', 'bychars' and 'bylines' are illegal for
readdata(), it cannot be used for reading CHARACTER data;

@@@@stop_character#Stop character
Data can be terminated by a "stop character" (default is '!').  With
'bychars:T' and 'bylines:T' this is recognized only as the first
character in a line.

You can change the stopping character by, say, 'stop:"$"'.  See topic
'vecread_keys' for details.

With readdata() or with 'byfields:T' and 'bywords:T' on vecread() or
readcols(), the stopping character must be at the start of a field or
word.  In other situations, it can be anywhere in the file.

@@@@skip_character#Skip character
Lines starting with a "skip character" specified by an argument of the
form, say, skip:"#" are skipped.  See topic 'vecread_keys' for more
information.

The default skip character is '#'.  If you don't want any skip
character, perhaps because there are lines in the file starting with '#'
that should be read, use 'skip:""' as an argument (not with readdata()).

@@@@writing_a_data_file_to_be_read_by_vecread#Writing a data file to be read by vecread()
You can write a file vecdata.txt of REAL data that vecread(),
readcols() and readdata() can read by

  Cmd> print(x,new:T,file:"vecdata.txt",header:F,labels:F,missing:"?")

where x is a REAL vector or matrix.  When x is a matrix, it is written
row by row as readcols() expects.  If you want it written column by
column, use x' as an argument.  You can specify the format or the number
of significant digits by keywords 'format' and 'nsig'.  See print().

====vecread_keys#files,input,output
%%%%
List of keywords that can be used on vecread() or readcols().
 Keyword               Value
 badkeyok              T or F*
 badvalue              REAL scalar or MISSING
 bychar                T or F*
 byfields              T or F*
 bylines               T or F*
 bypass                Nonnegative integer
 bywords               T or F*
 echo                  T or F
 file                  CHARACTER scalar file name
 go                    CHARACTER scalar with one character
 n                     Positive integer
 nofileok              T or F*
 printname             T or F*
 prompt                T* or F
 quiet                 T or F*
 silent                T or F*
 skip                  CHARACTER scalar with one character, default "#"
 skipthru              CHARACTER scalar with one character
 startline             Positive integer
 stop                  CHARACTER scalar with one character
 string                CHARACTER scalar or vector
* Default
%%%%
@@@@introduction#Introduction
This topic summarizes the use of keyword phrases as arguments to
vecread() which reads data items row by row from a text file.  Type
usage(vecread_keys) for a list of vecread() keywords.  See also topics
vecread() and 'vecread_file'.

Some of the examples use keyword 'string'.  See below for information.
@@@@______

     Keyword phrases specifying that CHARACTER data should be read
@@@@bywords_keyword#Keyword 'bywords'
bywords:T              Read CHARACTER data by words
  The file is interpreted as a sequence "words" or fields separated by
  commas, or "invisible" characters (spaces, tab characters and ends of
  lines).  The result is a CHARACTER vector, each element of which is a
  word from the file.

  Each word is empty or consists of a sequence of visible characters
  that are not commas.  An empty word occurs before a leading comma,
  after a trailing comma or between two commas with no intervening
  visible characters and is read as "".  For example
  vecread(string:",a ,, b,",bywords:T) returns vector("","a","","b","")

@@@@bylines_keyword#Keyword 'bylines'
bylines:T              Read CHARACTER data by lines
  Each line read becomes a single element of a CHARACTER vector.  The
  line-separating character "\n" is not included.  All other characters,
  including commas and invisible characters are read.  If no line starts
  with the stopping character, the length of the result is the number of
  lines in the file.

@@@@bychar_keyword#Keyword 'bychar'
bychar:T               Read CHARACTER data as separate characters
  Each character read, including commas, invisible characters and line
  separating characters, is read as a single element.  If no line starts
  with the stopping character, the length of the result is the number of
  characters in the file.
@@@@______

          Keyword phrase specifying how REAL data will be read
@@@@byfields_keyword#Keyword 'byfields'
byfields:T             REAL items read by "fields"
  The file is interpreted as a sequence of "fields" separated by commas
  or "invisible" characters.  The result is a REAL vector, each element
  of which is derived from a field in the file.

  A field is either empty or consists of a sequence of visible
  characters that are not commas.  An empty field occurs before a
  leading comma, after a trailing comma or between two commas with no
  intervening visible characters and is read as MISSING.  A non-empty
  field that is a well formed number (for example, -17, 3.14e73 or
  2.7182818) is read as that number.  If the number is too large to be
  represented in the computer (for example -3.1e3000), it is read as
  MISSING.  When a non-empty field is not a well formed number (for
  example 3.5a7 or Foo), it is read as badV when 'badvalue:badV' is an
  argument, or as MISSING otherwise.
@@@@______

                Keyword phrases specifying what to read
@@@@file_keyword#Keyword 'file'
file:FileName          Read from file FileName
  This is an alternate way to specify the file to be read.  That is
  vecread(file:FileName [,keyword phrases]) is equivalent to
  vecread(FileName [,keyword phrases]).  Filename must be a quoted
  string or CHARACTER scalar.

@@@@string_keyword#Keyword 'string'
string:CharVar         "Read" from CHARACTER scalar or vector CharVar
  CharVar is "read" as if it were a file whose contents are specified by
  CharVar.  Any instances of "\n" are treated as terminating a line.
  When CharVar is a vector, each element is assumed to start a new line.

  When CharVar is a CHARACTER vector, each element is read as for a
  CHARACTER scalar, with each element starting with a new line.  With
  bychar:T, "" is inserted between each element of CharVar.

  Examples:  Suppose S1 is "12\n34" and S2 is vector("12","34").

  vecread(string:S1 [,byfields:T]) and vecread(string:S2 [,byfields:T])
  return vector(12,34).

  vecread(string:S1, bywords:T or bylines:T) and vecread(string:S2,
  bywords:T or bylines:T) return vector("12","34")

  vecread(string:S1, bychars:T) returns vector("1","2","\n","3","4")

  vecread(string:S2, bychars:T) returns vector("1","2","","3","4")

@@@@n_keyword#Keyword 'n'
       Keyword phrase limiting the number of items to be returned
n:N                   No more than N items to be returned
  If fewer than N items are found before the stop character or the end
  of the file, a warning message is printed.  N must be a positive
  integer.

  Keyword 'n' is illegal as an argument to readdata().
@@@@______

     Keyword phrases specifying which lines should be read as data.
@@@@stop_keyword#Keyword 'stop'
stop:"$"               Set stop character to '$' (default is "!")
  Reading stops when a stop character is encountered.  With 'bychars:T'
  and 'bylines:T', a stop characters is recognized only as the first
  character in a line.  With 'byfields:T' and 'bywords:T' it is
  recognized only as the first character in a field or word.

  For numerical data, the stop character can be any punctuation
  character except '+', '-', ',', '?'  or  '.', that is, any of
  !"#$%&'()*/:;<=>@[\]^_`{|}~.

  For CHARACTER data, the stop character can be any punctuation
  character except ',', including '+', '-', '?' or '.'.

  For both numerical and CHARACTER data, the stop character can also be
  a "non-ASCII" character (code >= 128 = octal 200 = hexadecimal 80)
  such as "\200", "\377", "\x80" or "\xff", except when reading from
  CONSOLE.  This might be called for when you want to ensure the whole
  file is read, and you know the file does not contain non-ASCII
  characters.

@@@@bypass_keyword#Keyword 'bypass'
bypass:P               Skips past P lines starting with stop character
  When P > 0, nothing is read or echoed until P lines starting with
  the stop character have been read.  This allows you to read several
  sets of data on the same file provided they are separated by lines
  starting with the stop character.  This takes precedence over all
  other keywords that control which lines are read.  'bypass' is
  illegal with readdata().

@@@@startline_keyword#Keyword 'startline'
startline:M            Sets the first line to be scanned.
  Start reading on line M of the file, that is, the first M-1 lines are
  ignored and never echoed.  This takes precedence over all other
  keywords except bypass that control which lines are read.  Stop,
  skip, skipthru, and go characters are not recognized if they come
  before line M.  The default value for M is 1.  With bypass:P, reading
  starts on line M after the P-th line starting with the stop character.

@@@@skipthru_keyword#Keyword 'skipthru'
skipthru:"@"           Set skipthru character to '@' (no default)
  Lines up to and including the first line starting with the skipthru
  character are ignored.  They may be echoed, depending on the values of
  keywords 'echo', 'quiet' and 'silent'.

  The skipthru character can be any character.  When the skipthru
  character is "\n", reading starts after the first completely "white"
  line, that is, a line with no visible characters.

  The skipthru character takes precedence over and can be the same as
  the skip, stop or go characters.  It is ignored until after the lines
  skipped because of keywords 'bypass' and 'startline'.

@@@@go_keyword#Keyword 'go'
go:"%"                 Set go character to '%' (no default)
  Reading stops with the first line that does not start with the go
  character.  It is ignored until after the lines skipped because of
  keywords 'bypass' and 'startline'.

@@@@skip_keyword#Keyword 'skip'
skip:"#"               Set skip character to '#' (default is "#")
  Lines starting with skip character are ignored (they may be echoed).

  For numerical data, the allowable skip characters are the same as for
  stop characters.

  For CHARACTER data, any visible printing character, including a comma,
  may be a skip character.

  When the skip character is the same as the stop character (for
  example, stop:"#",skip:"#"), scanning will be stopped only if the stop
  character occurs after the first character in a non-skipped line (for
  example, by a line starting " #..." but not by "#...").

@@@@______
              Keyword phrases controlling what is printed
@@@@quiet_keyword#Keyword 'quiet'
quiet:F                Prints skipped lines, if any
  The lines printed are those skipped because of the skip or skipthru
  characters, but not those skipped by 'bypass:P' or 'startline:M'.

@@@@echo_keyword#Keyword 'echo'
echo:T or F            Control echoing of lines scanned.
  With echo:T, all lines scanned, including lines skipped because of the
  skip or skipthru character, are echoed to output.  With echo:F, the
  only lines echoed are skipped lines with quiet:F.

  When FileName is CONSOLE and the vecread() command is in a batch file,
  data that is read is echoed to output unless echo:F is an argument.
  This also happens in windowed versions even when not reading from a 
  batch file.

@@@@silent_keyword#Keyword 'silent'
silent:T               Suppress all warning messages and echoing
  This is incompatible with echo:T or quiet:F.

@@@@printname_keyword#Keyword 'printname'
printname:F             Suppress printing the name of the file read
  The default is printname:T except with string:CharVar.

@@@@prompt_keyword#Keyword 'prompt'
prompt:F               Suppresses prompt when reading from CONSOLE

@@@@______
                  Keyword phrases related to anomalies
@@@@badkeyok_keyword#Keyword 'badkeyok'
badkeyok:T             Ignore unrecognized or duplicate keywords
  Without badkeyok:T, unrecognized or duplicate keywords are considered
  errors.  This feature is useful in a macro where a line like
  @x <- vecread("data.txt",silent:T,badkeyok:T,$K) should work,
  even if the argument list to the macro includes keyword 'silent' or
  other keywords not recognized by vecread().

@@@@badvalue_keyword#Keyword 'badvalue'
badvalue:badVal        Replace unreadable REAL items by badVal
  When reading REAL data with badvalue:badVal an argument, any
  unreadable items are replaced by badVal, which must be a REAL scalar
  or MISSING.  Without badvalue:badVal, unreadable items are replaced by
  MISSING when 'byfields:T' is an argument and are skipped otherwise.

@@@@nofileok_keyword#Keyword 'nofileok'
nofileok:T             Failure to open the file is OK.
  When a file can't be opened, NULL is returned and no error message is
  printed.  Without nofileok:T, this is an error.
@@@@______

====vector()#variables,combining variables,character variables,null variables
%%%%
vector(x1,x2,...,xk [,KeyPhrases]) where x1, x2, ... all have the same
  type, REAL, LOGICAL, or CHARACTER, or are structures with components
  all of the same type
KeyPhrases can be labels:lab, notes:Notes and silent:T, where labs and
  Notes are CHARACTER scalars or vectors.
%%%%
@@@@usage#Usage
vector(x1, x2, ..., xk) combines scalars x1, x2, ... xk into a vector of
length k.  For example, you can enter a small set of data by
  Cmd> x <- vector(3.5, 9.6, 2.5, 2.3, 7.7, 2.6, 6.3, 6.5, 6.6, 4.1)

The arguments x1, x2, ..., xk can be REAL, LOGICAL or CHARACTER and must
all have the same type.  For example, you can create a CHARACTER vector
by
  Cmd> varNames <- vector("Length","Width", "Weight")

vector() is identical to cat().  However, cat() is a deprecated
function, that is, it will remain available for the immediate future,
but at some time it may be disabled.  Use vector() instead.

@@@@non_scalar_arguments#Non scalar arguments
Arguments may also be vectors.  In that case vector(x1, x2, ...., xk)
combines all the arguments into a single vector.  For example,
  Cmd> vector(run(3), run(3,1))
is equivalent to
  Cmd> vector(1,2,3,3,2,1).

More generally, any or all of the arguments may be vectors, matrices or
arrays, as long as they all have the same type.  In that case,
vector(x1, x2, ...., xk) has the same effect as vector(vector(x1),
vector(x2), ...., vector(xk)), combining all the elements of its
arguments into one long vector.  See the next paragraph for what
vector(x) does when x is a matrix or array.

vector(x) creates a vector from a matrix or array x by "unravelling" it,
with the first subscript changing fastest, the second changing next
fastest, etc.  Specifically, if the dimensions of x are n1, n2, ..., nk,
vector(x) is a vector with length n1*n2*...*nk, with elements
x[1,1,...,1], x[2,1,...,1], ..., x[n1,1,...,1], x[1,2,...,1],
x[2,2,...,1], ..., x[n1,2,...,1], ..., x[1,3,...,1], ...,
x[n1,n2,...,nk].  x may be REAL, LOGICAL, or CHARACTER.

@@@@structure_argument#Structure argument
When Str is a structure with n components, vector(Str) is a vector
equivalent to vector(vector(Str[1]),...,vector(Str[n])), defined
recursively if any component is a structure.  All the data components
must be of the same type, REAL, LOGICAL or CHARACTER.  This should not
be confused with strconcat() which combines structures into a larger
structure.

@@@@NULL_argument#NULL argument
Any argument of type NULL is ignored.  For example, vector(NULL, a) or
vector(a, NULL) are equivalent to vector(a).  When all arguments to
vector() have type NULL, so does the result.
@@@@______

@@@@attaching_labels_or_notes#Attaching labels or notes
You can specify labels for the first (and only) dimension of the result
using keyword 'labels'.  See topic 'labels' for details.

You can attach a CHARACTER vector of descriptive notes to the result
using keyword phrase 'notes:Notes'.  See topic 'notes' for details.

After
  Cmd> y <- vector(x)
where x is already a vector, y will have the same coordinate labels or
descriptive notes as x.

@@@@see_also#Cross references
See also topics 'vectors', 'structures'.
@@@@______

====vectors#variables,syntax
%%%%
Create a vector:    x <- vector(x1,x2, x3, ...)
Extract element(s)  x[i], i an integer scalar or vector or LOGICAL
  vector
%%%%
@@@@description#Description
A vector is an array with only one dimension, its length.  It can be
thought of as just a list of one or more numbers (REAL vector), logical
values (LOGICAL vector) or strings (CHARACTER vector).  You can't mix
different types of data in a single vector.  For that you need a
structure (see structure() and 'structures').

The most usual way to create a vector is to use vector():

@@@@examples#Examples
  Cmd> x <- vector(1,3,2.5,6) # create REAL vector

  Cmd> y <- vector("Hi","Lois") # create CHARACTER vector

  Cmd> z <- vector(T,T,F,F,T) # create LOGICAL vector

  Cmd> list(x,y,z) # all are vectors, having only 1 dimension
  x               REAL   4
  y               CHAR   2
  z               LOGIC  5

@@@@vectors_as_matrices#Vectors as matrices
Practically always, MacAnova commands treat a n by 1 matrix (column
vector) or a n by 1 by 1 ... by 1 array the same as a vector.  For
example, if y is a n by p matrix, then factor(y[,3]) is legal, even
though factor() expects a vector as argument, because y[,3] has only one
column.  Moreover, isvector(x) is True when x is a vector, a n by 1
matrix, or a n by 1 by 1 ... by 1 array.

Conversely, in a context requiring a matrix, practically always MacAnova
treats a vector of length n as a n by 1 matrix.

@@@@see_also#Cross references
See also topics vector(), isvector(), factor(), 'matrices'.
@@@@______

====vt()#plotting
%%%%
vt()
%%%%
@@@@usage#Usage
vt() (no argument) is designed to be used with a terminal emulator
implementing both VT100 and Tektronix 4014 emulation.  When running
MacAnova using such an terminal emulator, vt() automatically puts your
terminal in vt100 emulation mode using the character sequence obtained
by getoptions(tekset:T)[2].  See topic 'options'.

vt is normally not needed, since MacAnova should automatically switch
back to vt100 mode when a plot is finished if option 'tekset' has been
set appropriately.  See subtopic 'options:"tekset"'.

vt is implemented as a pre-defined macro (Unix/Linux versions only).

See topic vtx() if you are running MacAnova in an Xterm window on a
workstation.

@@@@see_also#Cross references
See also tek(), plot(), chplot(), lineplot(), boxplot(), showplot().
@@@@______

====vtx()#plotting
%%%%
vtx()
%%%%
@@@@usage#Usage
vtx() switches a Unix/Linux workstation Xterm terminal emulator to vt100
mode from Tektronix 4014 mode.  You don't normally need vtx since
MacAnova recognizes when it is running in a Xterm environment (the value
of environmental variable $HOME is "xterm") and automatically switches
back to vt100 mode after drawing a high resolution graph.

vtx is implemented as a pre-defined macro (Unix/Linux versions only).

See also topics tek(), tekx(), vt(), 'graphs', 'unix'.
@@@@______

====while#syntax,control
%%%%
while(Logical){statement1;statement2;...;}
%%%%
@@@@usage#Usage
while(Logical){statement1;statement2;....;} repeatedly executes the
statements enclosed in '{' and '}' as long as Logical has value True.
Logical should be a scalar LOGICAL variable or expression, but not a
constant expression.  Unless the last statement in {...} is empty (';;'
just before '}'), its value may be printed on every repetition.

The opening '{' must be on the same line as 'while' unless that line
terminates with '\'.

To avoid "infinite" loops, a 'while' loop will automatically terminate
after 1000 repetitions.  This limit can be changed by option
'maxwhile'.  After
  Cmd> setoptions(maxwhile:10000)
a 'while' loop will terminate after 10000 repetitions.

It is essential that one of the statements modify the variable(s) used
in the LOGICAL expression, or that a break or breakall statement is
used.  Otherwise the loop will repeated until 1000 (or value reset by
option 'maxwhile') repetitions are completed.

A 'while' statement does not have a value.  Hence such constructs as yyy
<- while(n > 0){...} or zzz + while(n > 0){...} are illegal.

@@@@syntax_elements_break_breakall_and_next#Syntax elements 'break', 'breakall; and 'next'
You can terminate a "while loop" prematurely using syntax elements
'break' and 'breakall' or pre-defined macro breakif().

You can skip to the end of a "while loop" using syntax element 'next'.
Be careful to modify the variable(s) used in the LOGICAL expression
before 'next' so as to avoid an "infinite" loop.

@@@@examples#Examples
Examples:
  Cmd> @s <- 0;@n <- length(x);while(@n>0){\
        @s <- @s+x[@n];@n <- @n-1;;};@s

This would print the sum of all the elements in x.

  Cmd> ex <- macro("@x <- argvalue($1,\"x\",\"real nonmissing\")
                  @dims <- dim(@x);@x <- vector(@x)
                  @neg <- 1-2*(@x<0);@x <- abs(@x);@eps <- 1e-12
                  @s <- @t <- @k <- 1
                  while(max(@t) > @eps*max(@s)){
                    @t <- (@x/@k)*@t
                    @s <- @s+@t;@k <- @k+1
                  }
                  array(@s^@neg,@dims)",dollars:T)

will create a macro ex() such that ex(x) computes exp(x) using a power
series, when x is a vector, matrix, or array.  See topics
'macro_syntax', argvalue(), macro() for information about writing
macros.

@@@@see_also#Cross references
See also topics 'for', 'if', 'break', 'breakall'.
@@@@______

====workspace#general
%%%%
The "workspace" consists of all MacAnova variables and macros.
Saving the workspace to a file
  save(fileName) saves whole workspace in binary format
  save(fileName,var1 [,var2 ...]) saves variables in binary format
  asciisave(fileName) saves whole workspace in text format
  asciisave(fileName,var1 [,var2 ...]) saves variables in text format
Restoring the workspace from a file
  restore(fileName [keywords])
Seeing contents of workspace
  listbrief([var1, var2, ...] [keywords]) just lists names
  list([var1, var2, ...] [keywords])  includes details
%%%%
@@@@definition_of_workspace#Definition of workspace
The "workspace" consists of all MacAnova variables and macros.  These
include not only variables and macros explicitly created by you as you
use MacAnova, but all pre-defined macros such as hist(), pre-defined
variables such as PI and variables such as RESIDUALS created as
"side-effects" of MacAnova functions.

The workspace "resides" in memory (RAM) and not on disk.  One
consequence is that when you quit MacAnova, your variables are lost.
Before you quit you can save a copy of the workspace on disk using
save() or asciisave().  In a later MacAnova session, you can use
restore() to recover the workspace you saved.  See save(), asciisave()
and restore().

@@@@cataloging_your_workspace#Cataloging your workspace
To get a catalog of everything in your workspace, type 'list()' or
'listbrief()'.  Using keyword phrases such as 'real:T' or 'nrows:100'
you can restrict the catalog to variables of particular types or sizes.
See list() and listbrief() for details.

@@@@deleting_items#Deleting items
Use delete() to remove items from your workspace.  Be careful not to
delete something you want to keep since there is no "undelete"
function.
@@@@______

====write()#output,files
%%%%
write(a, b, ...[,format:Fmt or nsig:m, header:F, labels:F, notes:T,\
  width:w, height:h, macroname:T, missing:missStr, name:setName]\
  [, file:fileName [,new:T]]]), Fmt, missStr, fileName, setName
  CHARACTER scalars, m > 0, w >= 30, h >= 12 integers
%%%%
@@@@usage#Usage
write(a, b, ...) prints objects (variables, expressions, macros) a, b,
..., ordinarily retaining more decimal places than print().  By default,
write() formats REAL items using the format identified by 'wformat' on
getoptions() output.  By default this specifies 9 significant digits in
floating point form but may be changed by setoptions().

Except for using a different default format, write() is identical with
print(), and recognizes the same keywords.  It is provided as an easy
way to print results with more significant digits than does print(),
without having explicitly to specify a format.  See print() for a full
description of the various keywords and output.

  Cmd> print(PI*run(5))
  VECTOR:
  (1)      3.1416      6.2832      9.4248      12.566      15.708

  Cmd> write(PI*run(5))
  VECTOR:
  (1)       3.14159265       6.28318531       9.42477796
  (4)       12.5663706       15.7079633

When either of keywords 'nsig' or 'format' are used, write() behaves
identically to print().

@@@@see_also#Cross references
See also topics setoptions(), matprint(), matwrite(), macrowrite(),
'options'.
@@@@______

====writedata()#output
%%%%
writedata(fileName,x1,x2,... [,missing:M] [, putNames:F] \
  [,fieldwidth:w  or  format:fmt]), CHARACTER scalar fileName, vectors
  x1, x2, ..., all with same length, CHARACTER scalars M, fmt,
  integer w > 0
writedata(x1,x2,..., keep:T [,missing:M] [, putnames:F] \
  [,fieldwidth:w  or  format:fmt])
%%%%
@@@@introduction#Introduction
writedata() is a macro designed to write one or more data vectors of
arbitrary as columns of a data file.  By default, columns are headed by
the variable names so reading the file using readdata() should restore
the variables.  Optionally, writedata() can return a CHARACTER scalar
containing an image of the file instead of writing it.

@@@@usage#Usage
writedata(fileName,x1,x2,...) writes data vectors x1, x2, ... as columns
in the file named by CHARACTER scalar fileName.

x1, x2, ... must be vectors of any type, REAL, LOGICAL or CHARACTER.  If
any vector is a factor and has row labels such that all cases with a
factor level have the same label, the row labels are written instead of
the factor levels.

REAL data are formatted using the current default format as returned
by getoptions(format:T), except that integer values are written as
integers with no decimal point.

CHARACTER data is written right justified in a field whose width is
taken from the default format.

LOGICAL data are translated to "T" or "F" and then written like
CHARACTER data.

MISSING values are written as "?" unless keyword 'missing' provides
another string; see below.

If a data vector is specified by a keyword phrase (x1:X[,1], for
example), the keyword is used as the vector name.  For this usage, the
keyword may not be 'keep', 'new', 'fieldwidth' or 'missing'.

Any data already in the file is destroyed unless 'new:F' is an
additional argument.

writedata(x1,x2,...,keep:T) acts similarly, except that no file is
written.  Instead, what would be written is returned as a CHARACTER
scalar to be assigned to a variable or CLIPBOARD.

writedata(fileName, x1, x2, ..., missing:M) and writedata(x1, x2, ...,
keep:T,missing:M) do the same, except that CHARACTER scalar M (for
example, "NA" or "*") is used instead of "?" for MISSING values.

By default, each column has the same width.  You can suppress this
behavior, so there is minimual space between columns, by keyword
'format'; see below.

@@@@keyword_putnames#Keyword 'putnames'
writedata(fileName, x1, x2, ..., putnames:F) and writedata(x1, x2, ...,
keep:T, putnames:F) do the same, except that no line of column headers
is written or returned.

@@@@keywords_format_and_fieldwidth#Keywords 'format' and 'fieldwidth'
When 'format:Fmt' is an argument, REAL values are written using format
Fmt.  Fmt must be a CHARACTER scalar which is a legal value for print()
keyword 'format'.  For details, see subtopic
print:"details_on_format_keyword".  If Fmt is of the form "w.dg" or
"w.df", where w and d are integers, each column will have width at least
w.  If Fmt is of the form ".dg" or ".df", there will be minimal space
between columns and columns will probably not be straight.

When fieldwidth:w is an argument, where w is a positive integer, columns
will be w characters wide and the format will be "w.dg", where d =
max(w-7,0).  You can't use 'fieldwidth' with 'format'.

@@@@see_also#Cross references
See also readdata(), clipwritedat(), print(), 'keywords', 'files'
@@@@______

====wtanova()#glm,anova
%%%%
wtanova([Model] ,Wts [print:F or silent:T, coefs:F, pvals:T, fstats:T]),
  Model a CHARACTER scalar, Wts a REAL vector.
%%%%
@@@@usage#Usage
wtanova(Model,Wts) is equivalent to anova(Model,weights:Wts).  See
anova() for details.
@@@@______

====wtmanova()#glm,anova
%%%%
wtmanova([Model] ,Wts[,print:F or silent:T, coefs:F, pvals:T, fstats:T,\
   sssp:F or T]), Model a CHARACTER scalar, Wts a REAL vector.
%%%%
@@@@usage#Usage
wtmanova(Model,Wts) is equivalent to manova(Model, weights:Wts).  See
manova() for details.
@@@@______

====wtregress()#glm,regression
%%%%
wtregress([Model], Wts [, print:F or silent:T, pvals:T])
  Model a CHARACTER scalar, Wts a REAL vector.
%%%%
@@@@usage#Usage
wtregress(Model,Wts) is equivalent to regress(Model,weights:Wts).  See
regress() for details.
@@@@______

====xrows()#glm
%%%%
xrows(variates [,factors]), variates and factors REAL matrices or
  vectors or NULL.
%%%%
@@@@usage#Usage
xrows(Variates, Factors) computes rows of an X-variable (design) matrix
corresponding to variate values in Variates and factor levels in
Factors, using the information saved by the preceding GLM command.

In the following, let nv = number of variates in the model and nf = the
number of factors in the model.

Variates should be either a REAL vector with length(Variates) = nv, or a
REAL matrix with ncols(Variates) = nv.  when nv = 0, Variates should be
NULL.

Factors should be either a REAL vector with length(Factors) = nf or a
REAL matrix with ncols(Factors) = nf.  All the elements of Factors
should be positive integers not exceeding the maximim level for each
factor.  When nf = 0, Factors should be NULL or should be omitted
entirely.

Let nrowv be 1 if Variates is a vector and nrows(Variates) otherwise,
and let nrowf be 1 if Factors is a vector and nrows(Factors) otherwise.
Then if nrowv != nrowf, you must have either nrowv = 1 or nrowf = 1 and
the single row of Variates or Factors is used for every row of the
output.

The result is a REAL matrix with max(nrowv, nrowf) rows.  Each row
consists of the values of the X-variables (design matrix) corresponding
to that row of Variates and Factors.

@@@@examples#Examples
Examples:
  After anova("y=x1+x2+a*b"), xrows(hconcat(x1,x2), hconcat(a,b)) is
  equivalent to xvariables().

  After regress("y=x1+x2"); xrows(x0) %*% COEF is equivalent to
  regpred(x0,seest:F,sepred:F) where x0 is a matrix of values for x1 and
    x2.

@@@@see_also#Cross references
See also topics xvariables(), modelinfo(), regpred(), glmpred(), 'glm'.
@@@@______

====xvariables()#glm
%%%%
xvariables(Model [, missing:val]), Model a CHARACTER scalar, val a REAL
  scalar
%%%%
@@@@usage#Usage
xvariables(Model) returns the full design matrix (matrix of X-variables)
associated with Model, including a column for the intercept (constant
term), if any.  Model must be a scalar CHARACTER variable or quoted
string.

See topic 'models' for information on specifying Model.

xvariables() (without a model) does the same except it uses the model
specified in STRMODEL which is usually the model used by the most recent
GLM (generalized linear or linear model) command such as regress(),
anova(), or poisson().

xvariables(Model, missing:val) and xvariables(missing:val), where val is
a REAL scalar, provides a value for cases with missing values.

Each variate in the model will appear as a column of the output.

Factors and interactions are translated to one or more "dummy" variables
with values 1, 0, or -1, or to products of dummy variables or of dummy
variables and variates.

Any row in which the dependent variable or any factor or variate is
MISSING is set entirely to 0, or, when 'missing:val' is an argument, to
val.  For example, xvariables(Model, missing:?)  or
xvariables(missing:?)  results in rows with missing data being set to
MISSING rather than to 0.

@@@@use_after_regress#Use after regress()
Note: When no model is specified and the previous command was regress(),
xvariables() does not compute dummy variables associated with any
factors in the model, but treats them as if they were variates.  Except
in this special case, the behavior of xvariables() differs sharply from
the behavior of modelvars() which retrieves factors and variates
unchanged.

@@@@no_factors_in_model#No factors in model
When there are no factors in the model, a regression of the dependent
variable on the columns of xvariables()[,-1], that is, the result of
xvariables() excluding the constant column, should yield the same
coefficients as does coefs() after regress(Model) or anova(Model).

@@@@with_factors_in_model#With factors in model
When there are factors in the model, the regression coefficients in such
a regression will differ from those produced by coefs() after
anova(Model), although the fitted values and residuals will be the same.
For example, following anova("y=a.x"), where a is a factor and x is a
variate, the coefficients from coefs("a.x") will be the slopes in a
model fitting separate lines for each level of a, but with a common
intercept.  This is not the parametrization implicit in a regression of
y on the columns of xvariables[,-1].

@@@@see_also#Cross references
See also topics varnames(), modelvars(), modelinfo(), 'models'.
@@@@______

====yates()#glm,anova
%%%%
yates(x), x a REAL vector
%%%%
@@@@usage#Usage
yates(x) performs Yates' algorithm for the effects in a 2-series
factorial experiment.  The argument x should be a REAL vector
(univariate case) or matrix (multivariate case) containing the 2^k
observations in standard order, that is, the levels of the first factor
changing most rapidly.

When x is a vector, the value is a vector of the (2^k)-1 effects in
standard order and divisor 2^(k-1).  For example, for a 2^3 experiment
with data vector(x111,x211,x121,x221,x112,x212,x122,x222), the result is
vector(A, B, AB, C, AC, BC, ABC), where
  A  = (-x111 + x211 - x121 + x221 - x112 + x212 - x122 + x222)/4
  B  = (-x111 - x211 + x121 + x221 - x112 - x212 + x122 + x222)/4
  AB = (+x111 - x211 - x121 + x221 + x112 - x212 - x122 + x222)/4
and so on.  The mean, (x111+x211+x121+x221+x112+x212+x122+x222)/8, is
not included.

In matrix notation, the k = 3 case can be expressed as
  [ A   ]         [ -1   1  -1   1  -1   1  -1   1 ]  [ x111 ]
  [ B   ]         [ -1  -1   1   1  -1  -1   1   1 ]  [ x211 ]
  [ AB  ]         [  1  -1  -1   1   1  -1  -1   1 ]  [ x121 ]
  [ C   ] = (1/4) [ -1  -1  -1  -1   1   1   1   1 ]  [ x221 ]
  [ AC  ]         [  1  -1   1  -1  -1   1  -1   1 ]  [ x112 ]
  [ BC  ]         [  1   1  -1  -1  -1  -1   1   1 ]  [ x212 ]
  [ ABC ]         [ -1   1   1  -1   1  -1  -1   1 ]  [ x122 ]
                                                      [ x222 ]

When x is a matrix with m columns, the value is a (2^k) - 1 by m matrix,
each column of which is the result of applying Yates's algorithm to the
corresponding column of x.
@@@@______

====yulewalker()#time series
%%%%
yulewalker(vec [, inverse:T]), vec a REAL vector or matrix.
%%%%
@@@@usage#Usage
yulewalker(Rho) computes a REAL vector of autoregressive (AR)
coefficients phi[1], phi[2], ... phi[p] of a p-th order AR time series
whose autocorrelations r[1], r[2], ... r[p], are in REAL vector Rho,
where p = nrows(Rho).  The values of phi satisfy the Yule-Walker
equations rho[j] = sum(phi[k]*rho[j-k],j=1,...,p), k = 1,...,p, with
rho[0] = 1, rho[-j] = rho[j].

When Rho is a matrix, yulewalker(Rho) computes AR coefficients from each
column separately, that is, yulewalker(Rho)[,j] = yulewalker(Rho[,j]), j
= 1,...,ncols(Rho).  If Rho is a generalized matrix (at most two
dimensions >= 1), yulewalker(Rho) = yulewalker(matrix(Rho)) (see
'matrices', matrix()).

When any column of Rho is not a valid autocorrelation function, that is,
if the implied Toeplitz correlation matrix is not positive definite,
yulewalker() prints a warning message, sets the element in the result
where the violation occurred to the most extreme value possible and any
subsequent elements to zero.  For instance, yulewalker(vector(-.3,
-.9,.5)) returns the result vector(-.6, -1, 0).

@@@@use_in_estimation_of_AR_model#Use in estimation of AR model
A typical usage is
  Cmd> rhohat <- autocor(y, 10) # compute 1st 10 autocorrelations

  Cmd> phihat <- yulewalker(rhohat)

phihat is a vector of length 10 containing the coefficients of the
autoregressive series whose first 10 autocorrelations are the same as
rhohat.  Thus yulewalker() provides a method-of-moments way to estimate
the parameters of an AR (autoregressive) model.

When time series y is in fact a normal stationary AR series of order
length(rhohat), these estimates are asymptotically equivalent to maximum
likelihood estimates.

NOTE: autocor() is a macro in file tser.mac.  Type help(autocor) for
details.

@@@@inverse_keyword#Keyword 'inverse'
yulewalker(Phi,inverse:T) computes auto correlations corresponding to
autoregressive coefficients in the columns of REAL vector or matrix Phi.

Effectively yulewalker(Phi,inverse:T) is the inverse function to
yulewalker() in that yulewalker(yulewalker(Rho),inverse:T) should the
same as Rho, except for rounding error.

One important usage is
  Cmd> rho <- yulewalker(padto(Phi,n), inverse:T)

where n >= nrows(Phi).  This computes the first n autocorrelations of
the autoregressive series with autoregression coefficients in Phi.

@@@@see_also#Cross references
See also padto(), partacf(), toeplitz().
@@@@______

====zinterval()#probabilities,descriptive statistics,comparisons
%%%%
zinterval(x[,y],cover:fraction,var:variance,[upper:T or lower:T])
%%%%
zinterval() computes a z-confidence interval for a population mean
or difference of population means, depending on whether one or two
variables are given as arguments.  By default, zinterval() computes
a two-sided interval, but you may choose one-sided alternatives
by using one of lowerb:T or upperb:T.

You specify the coverage rate via cover:value. You specify the
variance via var:variance.  For a two-sample interval, you may specify
different variances by using a vector of length two.

The output is a vector containing the estimate and interval bounds.

Because the variance of the data must be known, these intervals are
rarely used in practical data analysis.


====ztest()#probabilities,descriptive statistics,comparisons
%%%%
ztest(x[,y],null:val,var:variance,[upper:T or lower:T])
%%%%
ztest() performs a one- or two-sample z-test, depending on whether
one or two variables are given as arguments.  By default there is
a two-tailed alternative, but you may choose one-sided alternatives
by using one of lowertail:T or uppertail:T.

You specify the null value via null:value.  You specify the
variance via var:variance.  For a two-sample test, you may specify
different variances by using a vector of length two.

The output is a vector containing the z-statistic and the p-value.

Because the variance of the data must be known, these tests are
rarely used in practical data analysis.


_E_O_F_#This should be the last line, an internal End Of File marker
