(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 Linux. Installation instructions for MacAnova are in file Install.msw.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 Command line options 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 Linux versions is http://www.stat.umn.edu/macanova/downloadlinux.html It is set up to make it relatively easy for you to download the file you need. Starting MacAnova From an xterm or similar, give the command macanovacpc for the GTK version of MacAnova, or give the command macanova for the nonwindowed version. (The windowed version uses the Carapace toolkit, which explains the cpc in the name.) KDE, Gnome, and similar systems also allow you to start a program by double clicking it from a file browser. They also allow you to set up system menu items that will launch a program. MacAnova has many, many command line options letting you specify files, paths, etc. In fact, the reason that the installer builds a little one line shell script is to add a command line option giving the path to the help and macro files. Command line options are discussed in a later section. Executing Commands In the GTK version, 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. In command line MacAnova, you type your commands after a prompt 'Cmd> '. Stopping MacAnova You exit MacAnova by typing 'quit', 'bye', 'stop' or 'end' at the prompt, that is, for example, Cmd> quit On the GTK version, 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, type quit(F). Interrupting MacAnova In the GTK version, 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. In the command line version, Control+C brings you back to the 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 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). 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. In these cases, MacAnova will handle all the slashes automatically. 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 Linux, DATAPATHS is initialized to contain ~/MyMacAnovaFiles and INSTALL/SharedSupport, where ~ is the user's home directory and INSTALL is the directory in which MacAnova is located (typically /usr/lib/macanova). If you put your own copy of a file that MacAnova is looking for in ~/MyMacAnovaFiles, 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 Windows 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. Command line options As alluded to above, you may make use of command line options in Windows by embedding the options in the command properties of the MacAnova for Windows item on the Start menu. You may also use these options directly if you work from the command line. Here are the options: -q Suppress printing banner -batch batchFile #Simulate batch("batchFile") -restore restoreFile Simulate restore("restoreFile") -f startupFile #Use startupFile instead of Macanova.ini.txt -prompt Prompt Use Prompt as input prompt -bprompt Prompt Use Prompt as batch prompt (with -batch) -e Expression Evaluate Expression before doing anything else -help helpFile Use helpFile as default file for help information -macro macroFile #Add "macroFile" to variable MACROFILES -open windowFile #Load windowFile into window at launch -data dataFile #Add "dataFile" to variable DATAFILES -path dataPath #Add "dataPath" to variable DATAPATHS -addhelp hFile #Add "hFile" to variable HELPFILES -home homePath Set variable HOME to "homePath" -appdir appPath Set the MacAnova root directory to "appPath" -config confFile Set the MacAnova preferences file to "confFile" -l nlines Set height for dumb plots to nlines (0 or >= 6) -w ncols Set width for dumb plots to ncols (>= 20) -hist count Keep count old commands in history options marked with # may be used multiple times 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