     (This document is best viewed in a monospaced font)
                           M A C A N O V A   5.04
                                 Release 1
                            August 15, 2005

    An Interactive Program for Statistical Analysis and Matrix Algebra
          Copyright 2005, Gary W. Oehlert and Christopher Bingham

This file pertains to versions of MacAnova for Mac OS X. 

Installation instructions for MacAnova are in file Install.osx.txt.


Contents of this file:
  Introduction
  Documentation for MacAnova
  Where to get MacAnova
  Starting MacAnova
  Executing Commands
  Stopping MacAnova
  Interrupting MacAnova
  Using help(), guihelp(), and usage()
  File names and backslashes
  Search Paths
  User Interface Features
  Importing Data From Other Programs
  Exporting Data For Use by Other Programs
  Exporting and Saving Graphs

                              Introduction
In spite of its name, MacAnova is available for Windows, Macintosh,
and Linux, not just Macintosh.  And it does a great deal more than
Analysis of Variance.

MacAnova was conceived and programmed and is maintained by Gary W.
Oehlert and Christopher Bingham, School of Statistics and is
Copyright (C) 2005 by them (kb@stat.umn.edu and gary@stat.umn.edu).

MacAnova is distributed under the terms of the GNU Public License,
Version 2.  See file Copying.txt distributed with MacAnova.

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

Reports of bugs should be e-mailed to kb@stat.umn.edu.

There is a MacAnova mailing list.  You can subscribe through the
MacAnova home page
  http://www.stat.umn.edu/macanova/macanova.home.html

                       Documentation for MacAnova
There are several sources of documentation for MacAnova: the on-line
help included with MacAnova, a User's Guide for Version 4.07 and a
"primer" entitled Introduction to MacAnova.  The primer was current
for Release 2 of version 4.12.  The User's Guide and Introduction are
both a little out of date, but their information on basic MacAnova
commands remains valid.

Help information is always up to date and exists in three forms.
  1.  The help files readable from within MacAnova by help() and usage()
  2.  The MacAnova Reference Manual (in pdf format) which is
      generated automatically from the help files.
  3.  A set of HTML files that can be read through your web browser.
      These are also generated automatically from the help files.

All documentation and forms of help are included with a standard
installation of MacAnova.

The most recent manual is the MacAnova Users' Guide for Version 4.07.
This is a complete manual for Version 4.07 and virtually everything in
it still applies to current MacAnova.  Of course, it doesn't describe any
features added since 4.07 was released.  The exception to this is the
appendices that descript platform-specific features; some of these 
have changed dramatically in Version 5.00.

Like all manuals that try to provide a comprehensive description of a
complex program, the User's Guide may be hard going if you are new to
MacAnova.  Much more accessible, but far less comprehensive, is "An
Introduction to MacAnova." It is up-to-date through release 3 of
MacAnova 4.12.  

Information on how to use the on-line help is later in this document.

                         Where to get MacAnova
Everything publically available about MacAnova, including the latest
Macintosh, Windows and DOS versions, documentation, and source, is
available via the Internet.  On the World Wide Web, our home page is

  http://www.stat.umn.edu/macanova/macanova.home.html

The starting point for downloading the Mac OS X version is

  http://www.stat.umn.edu/macanova/downloadmac.html

It is set up to make it relatively easy for you to download the files you
need.

                           Starting MacAnova
Simply double click on the MacAnova application file to start MacAnova.
You may also drag the MacAnova icon to the dock, to make it easily
available.

The Macintosh should recogonize files with a .mvout, .mvsave, or
.mvbat extension as belonging to MacAnova.  Double clicking on one
of those files will launch MacAnova and either display the output
file, restore the saved variables, or execute the batch file.  Files
with creator mat2 should also be recognized by MacAnova.

                           Executing Commands
Commands are typed in the lower panel of the command/output window. 
When your command is finished and you type enter, the command will be
executed and the output will appear in the top panel.  The up and down
arrow keys move up and down through a history of commands.  

There are also several buttons along the bottom of a command window: Undo,
Execute, Back, Forward, and Clear.  Back and Forward move up and down
through the command history.  If the last thing that you did was a command,
then Undo erases the output and puts the command back on the command line.
(Note, it does not undo the results of the command, just the printed
output.)  Clear will clear the command panel.  Execute copies anything that
is selected in the upper panel to the end of the command line and then
adds an enter (which will usually execute the command).

If your command is not being accepted, you probably have an unmatched
quote (") or left curly bracket ({).  Close the quotes and curly brackets
to get things going.  Unmatched quotes, parentheses, braces, and brackets
whould be highlighted by color.

                           Stopping MacAnova
You exit MacAnova by typing 'quit', 'bye', 'stop' or 'end' at the
command line. 

You can also select Quit on the File menu.  You are normally asked if
you want to save your workspace and the command/output window in files. 
To bypass this, use the command quit(F).

                         Interrupting MacAnova
Select Interrupt on the File menu or press Control+I or click the
Interrupt button at the bottom of the command window (these may take a
while to be noticed).  This will stop the current calculation and give
you a new prompt.  


                     Using help(), guihelp(), and usage()
help(), guihelp(), and usage() access extensive online help on the
basic features and commands in MacAnova.  Help information is contained
in several files distributed with MacAnova.  The names of the files
to be searched for help information is stored in the variable HELPFILES.
HELPFILES is initialized to a standard set of files.

To get help for a topic from within MacAnova, type help(topicName) at
the prompt followed by Return; for example, help(boxplot)
By default, help() searches all the standard files containing help.
help(topic) will print the help for topic in the output window.  In
contrast, guihelp(topic) will open a little browser window to display
the same information.  This html help has links to allow you to
view other related topics easily.  Selecting Help from the Help menu
also invokes guihelp.  If no text is selected, menu Help is
just like giving the command guihelp().  If text is selected, say
boxplot, then menu Help is equivalent to the command guihelp(boxplot).

usage(topic) displays a very brief summary of help on the topic.

You can get an annotated list of the topics in the help file associated
with one of the standard macro files, Arima.mac, Design.mac,
Graphics.mac, Math.mac, Mulvar.mac, Regress.mac and Tser.mac by, for
example, help(index:"regress") and help(index:"math").  The names of the
topics containing these indices is in pre-defined variable HELPINDICES.

There are many, many help topics.  The most convenient way to look
around at help is through the html help.  Simply asking for Help from
the menu will bring up a contents page listing all of the topics from
all of the help files, as well as giving some keywords to help find
related topics.

You may do something similar at the command line; the command help("*")
will print a complete list of the hundreds of help topics, but it's a
little overwhelming.

Help has many other features, including keyword search, subtopic search,
and so on.  Look at the help on help to learn about these more 
advanced features.

                     File names and backslashes
In MacAnova commands that take a file name as an argument,  you 
may give an empty quoted string as the file name, that
is, "".  Then MacAnova will bring up a dialog box to allow you to
select the file.  

MacAnova uses the backslash character \ inside quotes to flag special
characters that may not have their usual meaning. This is called
``escaping'' the character. 

Just to be concrete, here is an example escaping a quoted string.
Quotation marks denote a string in MacAnova, so in the expression
"String without quotes"
the string is delimited by the quotes, but the quotes are not part
of the string.  However, now look at
"\"String with quotes\""
The \" means a real, honest to goodness quote character inside the
string.  Other useful escaped characters include \t (tab character),
\n (newline character), and \\ (backslash itself).  

                    Search Paths
MacAnova often looks for files, including data files, help files,
macro files, and so on.  If you give a complete path to the file,
then everything is easy.  If you give an incomplete path or just
the file name, then MacAnova must look for the file.  The list of
places MacAnova looks is called the search path.  

MacAnova always first tries to open a file in the current directory.
If that fails, then MacAnova will look sequentially in each of the
directories given in the MacAnova CHARACTER vector DATAPATHS.  You
may add additional directories to search by using the macro
adddatapath(), or by manipulating DATAPATHS directly.

On Mac OS X, DATAPATHS is initialized to contain 
~/Library/Application Support/Macanova (where ~ is your home
directory) and the SharedSupport folder inside the MacAnova program
bundle.  If you put your own copy of a file that MacAnova is looking
for in ~/Library/Application Support/MacAnova, then MacAnova will
find your copy and not its original copy.  This is useful
for dealing with your own customized version of a macro file
or help file.

If you put a file named macanova.config in your search path, then
that file will be read at startup for various stylistic settings on
MacAnova.  The contents of this file are in a Name: value format.
At present, you can set the following features:

windowOffset: count
        number of pixels to offset each additional command window
mainPrompt: string
	prompt to print on output indicating a command (the string
	ends at the end of line)
textWindowSize: width height
	default size of a command window
historyLength: count
	number of past commands to keep in history
textFontSize: count
	font size for command window
textFontFamily: string
	choices are MODERN, ROMAN, SWISS, DECORATIVE, and SCRIPT
	anything other than MODERN (monospaced) is a bad idea
textFontFaceName: string
	if you want to specify a specific type face
textFontWeight: string
	choices are NORMAL, LIGHT, and BOLD
textFontStyle: string
	choices are NORMAL, SLANT, ITALIC
textFontColorName: string
	choices are things like GREEN or ORANGE
textFontColorVals: r g b
	RGB values for the text color; RGB values over ride named colors
textBackgroundColorName: string
textBackgroundColorVals: r g b
	as for textFont


                User Interface Features 
You type commands in the bottom panel of a Command/Output window;
results are printed above.  This window is referred to
simply as the "command window" below.  It is initially Untitled, but
takes the name of a file when it is saved.  The command window is
fully editable.  It can be saved to a file or printed by items on
the File menu.

MacAnova has nine menus: File, Edit, Windows, Data, Variables,
Calculations, Statistics, Graphics, and Help.  Items on the
File, Edit, and Windows menu deal with creating, saving, printing,
displaying, editing, scrolling, and manipulating command and graphics
windows.  The Help menu brings up html help in a separate window.
The remaining five menus access a subset of common MacAnova commands
for reading/creating data, manipulating variables, doing mathematical
calculations, performing statistical analyses, and displaying
graphics.  Most of these menu items bring up dialog boxes to gather
information from the user before creating a MacAnova command to
do the desired task.  NOTE: MacAnova can do many things through
typed commands that cannot be done through the menus.

You can open additional command windows using New Window on the
Windows menu or Open... on the File menu.  The latter allows you to
read a text file, usually the contents of a command window from a
previous run, into a new window.  When there is more than one command
window, you can switch between them using entries on the Windows menu.

You can save the contents of the front command window on disk using Save
Window or Save Window As on the File menu.  Note:  Saving the window
does not save the contents of the workspace.  You save the workspace
by using Save Workspace on the File menu.

You may have multiple graphics windows (Graph 1, ...).  Plotting
commands draw into the first graph window that is not in use, or you
can specify the window to be used by keyword phrase window:x, for
example plot(x,y,window:2).

You can print a graph window or save it to a file in one of several
graphics formats by choosing Print or Save on the File menu.  You can
use Copy on the Edit menu to copy to the Clipboard any graph window. 
You can then paste it into another program such as Microsoft Word or
PowerPoint.  You bring a graph window to the front by selecting it on
the Windows menu or by pressing F1, F2, etc.

When a graph window is in front, you can bring the command window to the
front by pressing Return or Enter or by selecting a command window on
the Windows menu.

Here is a table of the accelerator keys and their actions

Ctrl+O       Open a text file in a new output window
Ctrl+S       Save the contents of an output window to a file
Ctrl+I       Interrupt execution
Ctrl+K       Save the workspace
Ctrl+R       Restore a workspace
Ctrl+Q       Quit

Ctrl+Z       Undo
Ctrl+X       Cut
Ctrl+C       Copy
Ctrl+V       Paste
Ctrl+Y       Copy selection to command line
Ctrl+U       Copy selection to command line and add return to execute
Ctrl+B       Back in command history
Ctrl+F       Forward in command history

Ctrl+W       Close command window
Ctrl+N       New command window
Ctrl+T       Scroll to top of output window
Ctrl+E       Scroll to bottom of output window
Ctrl+A       Move mouse focus to command pane

F1..Fk..F12  Raise graph window k
Ctrl+1,2,... Raise command window k    

Ctrl+L       Help

Shift+Enter  In command pane, add return to end of command (usually
             will execute)

Up or down
arrows       In command pane, move back and forward in command history
             In output pane, move up and down in window

Left/right   Alone, these move left and right in a window.  In
             combination with control, or shift, etc, the action
             is platform dependent.

                   Importing Data From Other Programs
MacAnova can read data in plain text (ASCII) from files or from the
clipboard.  Transferring through the clipboard is often the easiest
way to get data from another program into MacAnova.  There are several
menu items under the Data menu that can read from files or the
clipboard, and there are several commands that you can enter directly
do do the same.  For example, if you have your data in a spreadsheet
such as Excel, you can select a grid of data and copy it to the
clipboard.  Then in MacAnova, choose the Data menu item to read the
appropriate form of data (you may have columns with column labels,
or without labels, or you may have a single vector, etc.).

As an alternative, most programs can save data by writing a plain
text (ASCII) file.  MacAnova can read plain text files with data
formatted in several ways.  Again, simply choose the Data menu item
that corresponds to the format of your data file.

MacAnova recognizes Windows/DOS, Macintosh and Unix end of line
characters.  MacAnova will recognize '?', 'NA', '*' and '.' as
missing value codes and by default will skip lines starting with
the character '#'.  See help for vecread and readdata for more detail
on reading from files or the clipboard.

Here is a brief list of MacAnova commands useful for reading data:

vecread        Fundamental file reading command, which can read data
               in several forms.  It can also be used to read from a
               character string or the clipboard.
readdata       Read columns from a file.
read           Read data written in a special MacAnova format.
clipreaddata   Read columns from the clipboard.
fromclip       Read a vector or matrix from the clipboard.

The Data menu items for reading data are just front ends to these
standard commands.  See the help for these commands, as each has
its own strengths and abilities.  

NOTE: these commands have features and options that cannot be
accessed through the menus, so it pays to check them directly if the
menu items do not meet your requirements.  For example, if the first
data item in a column is not readable as a number, readdata assumes
the entire column to be character data and then makes it into a factor
that can be used in ANOVA models, with the character data as case
labels.  On readdata or clipreaddata, you can add 'factors:F' to
suppress this behavior.

                Exporting Data For Use by Other Programs
Exporting data is just the reverse of importing, you can send data
to a file or to the clipboard.  To write data to a file, use print()
or matprint() (which differ only slightly).  For example,
  matprint("",x,header:F,sep:",",new:T,nsig:17,missing:-99999.99)
or
  matprint("",x,header:F,sep:"\t",new:T,nsig:17,missing:-99999.99)
will export the vector or matrix x to a file, print no header, use
a comma or tab to separate values, not append to any previous file
of the same name, use 17 significant digits, and replace missing 
values by -99999.99.  The empty file name "" will bring up a dialog
box allowing you to choose a file.

To put a real matrix X on the clipboard with columns separated by
tabs, use
   toclip(x)
In most spread sheet programs, you can then import x by selecting
the right size rectangle in the spread sheet and selecting Paste on
the Edit menu.  If the spreadsheet prefers comma-separated
fields use,
   CLIPBOARD <- paste(x,sep:",",multiline:T,format:".17g")
See help topic 'clipboard' for information about special variable
CLIPBOARD which is "connected" to the Clipboard.

                      Exporting and Saving Graphs
You may copy a graphics window to the clipboard by choosing Copy
from the Edit menu.  You can then paste it into a word processor or
other file.  Alternatively, from the file menu, you can choose
Save as ...  This allows you to save the graph to a file in one of
several formats, including jpg, tiff, png, and PostScript.  You 
may also print the graph by selecting Print on the File menu.

On any plotting command, when you include as an argument the keyword
phrase file:fileName, where fileName is a CHARACTER variable or quoted
string (including the empty string "" in the Mac OS X version), plotting
information is written to a file in the form of PostScript commands.
You can print the resulting file on a printer that understands
PostScript.  With some word processors it is possible to embed the
Postscript directly in a document.


Happy Computing!

Gary W. Oehlert                         gary@stat.umn.edu
Christopher Bingham                     kb@stat.umn.edu
University of Minnesota
School of Statistics
313 Ford Hall
224 Church Street, S.E.
Minneapolis, MN 55455

August 15, 2005

