(This document is best viewed in Monaco 9 or Courier 10 font) M A C A N O V A 4.03 An Interactive Program for Statistical Analysis and Matrix Algebra Copyright 1997, Gary W. Oehlert and Christopher Bingham MacAnova is conceived and programmed by Gary W. Oehlert and Christopher Bingham, Department of Applied Statistics and is Copyright (C) 1997 by them (kb@stat.umn.edu and gary@stat.umn.edu). It is distributed under the terms of the GNU Public License, Version 2. See file COPYING distributed with MacAnova. Briefly, this means that MacAnova may be freely copied and distributed, but may not be resold. The source is available by anonymous ftp or other equivalent retrieval from umnstat.stat.umn.edu. Any changes made to the source must be clearly marked. The protected mode version of MacAnova was compiled using the DJGPP compiler. Source and executable for DJGPP can be retrieved via anonymous ftp from oak.oakland.edu (in pub/simtelnet/gnu/djgpp). There is no warranty of any kind for MacAnova, either expressed or implied. MacAnova is distributed "as is". See file COPYING for a more complete statement. Reports of bugs should be sent to kb@stat.umn.edu. MacAnova 3.1 was a major revision by Christopher Bingham of MacAnova 2.41 developed by Gary Oehlert. Version 3.35 and now 4.04 represent substantial improvement over 3.12, including many new functions and features. MacAnova was originally developed for the Macintosh(tm) computer but there are now Unix, Windows, Motif and DOS versions, too. This document describes MacAnova on a Intel based computer running DOS, Windows with Win32s, or Windows 95. Specifically it details how to start MacAnova and summarizes the features that are specific such computers. It also described the documentation available and details how to retrieve the most recent version. Installation instructions for MacAnova are in file INSTALL.TXT. Documentation for MacAnova There are three basic sources of documentation for MacAnova: the on-line help included with MacAnova, a preliminary edition of a User's Guide for Version 4.04 and a somewhat out-of-date introductory document. The User's Guide is complete except for some of the Appendices. It supersedes all previous manuals. MacAnova has online help via the function help(). To get help for a topic, type help(topicName) followed by a return at the prompt; for example, help(boxplot) or help(anova). Basic information about help can be obtained simply by help(); full information about help can be obtained by help(help). A complete list of help topics can be obtained by help("*") (the star wildcard character means match anything). This will print a list of almost 300 help topics available. A preliminary edition of a manual for Version 4.04 has been released as "MacAnova User's Guide" by Gary W. Oehlert and Christopher Bingham. It is complete except for appendices describing features specific to the DOS, Windows, Unix and Motif versions of MacAnova. When complete, it will be issued as University of Minnesota School of Statistics Technical Report #617. This manual is available from St. Paul Bookstore University of Minnesota 1420 Eccles Avenue St. Paul, MN 55108 It sells for about $12. You can get information on pricing, shipping, etc. or place a credit card mail order by calling 612-624-9200. You can Fax a credit card order to 612-625-2229. Accepted credit cards are Mastercard, Visa, and Discover Card only. Like all manuals that attempt to provide a comprehensive description of a complex program, the User's Guide may be difficult going for someone new to MacAnova. Much more accessible, but far less comprehensive, is "An Introduction to MacAnova," School of Statistics Technical Report #600, as revised September 1995. This is available at the University of Minnesota as a course packet for several Statistics Courses. It currently describes an earlier version (3.36) but will be updated soon. It is also available as PDF file Intro.pdf and PostScript file Intro.ps; you may retrieve these via anonymous ftp from the URL ftp://ftp.stat.umn.edu/pub/macanova/docs/{Intro.ps or Intro.pdf}. You should be able to print Intro.ps on any PostScript printer. Intro.ps is included in the diskette distribution. See file CHANGES.TXT for an incomplete summary of enhancements to MacAnova that are not described in the March 1993 User's Guide for MacAnova 3.11 Where to get MacAnova Everything publically available about MacAnova, including latest versions, documentation, and source, is available via the Internet. On the World Wide Web, our home page is at http://www.stat.umn.edu/~gary/macanova/macanova.home.html It is set up to make it easy for you to down load the files you need. Click on "Download" and then on "iBM PC compatible versions" where you are given a choice of "Windows version", "Real mode (BC) version" or "Protected mode (DJ) version". You can also retrieve the files by ftp from ftp.stat.umn.edu. They are in directory pub/macanova/mac. Using gopher to retrieve stuff from stat.umn.edu, Software Archive: MACANOVA gets you to pub/macanova. Directories mac, dos, aux_file and src include files for Macintosh versions, Dos/Windows versions, auxilliary text files and source. Directory docs/manual contains PDF files for the User's Guide. Using gopher to retrieve stuff from stat.umn.edu, Software Archive: MACANOVA gets you to pub/macanova. A mirror archive is being maintained at statlib (http://lib.stat.cmu.edu/). Changes and new releases should be available there within 24 hours. See file Changes.txt for an incomplete summary of enhancements to MacAnova that are not described in the March 1993 User's Guide for MacAnova 3.11 There is extensive online help, including a number of entries of general interest. Type 'help(macanova3)' in MacAnova to get a summary of differences from Version 2.4x as well as enhancements. Type 'help(macintosh)' to get a summary of Macintosh specific features. Type 'help(updates)' to get a summary of the history of changes to MacAnova. Starting MacAnova The two non-windowed versions of MacAnova should be invoked at the DOS prompt by macanobc [-q] [File options] [Screen options] or macanodj [-q] [File options] [Screen options] where items in [...] are optional. If -q is present, the startup message will not be printed. File options The possible file options are -f initFile, -restore saveFile, -batch batchFile, -help helpFile, -macro macroFile, and -data dataFile, where xxxxFile is the name of a DOS file. You can use -r, -b, -h, -m or -d in place of -restore, -batch, -help, -macro and -data, respectively. If -f initFile is specified, file initFile is executed silently as a batch file at startup instead of file MACANOVA.INI (see help topic customize). If -restore saveFile is specified, the equivalent of 'restore("saveFile")' is executed at startup and MACANOVA.INI is not read. See help topics customize, restore(). If -batch batchFile is specified, the equivalent of 'batch("batchFile")' is executed after initialization. See help topic batch(). If -help helpFile is specified, MacAnova will use helpFile as the file of help documentation rather than the default help file. You can also change the help file within MacAnova by help(file:fileName). See help topic help. If -data dataFile is specified, MacAnova CHARACTER variable DATAFILE will have "dataFile" as value. DATAFILE is used by pre-defined macro getdata to make it easy to read data from a standard file. If -data dataFile is not specified, DATAFILE will have default value "Path/MACANOVA.DAT", where Path is the complete pathname of the directory in which MACANOVA.EXE resides. See help topic getdata. If -macro macroFile is specified, MacAnova CHARACTER vector MACROFILES will have "macroFile" as its first element. MACROFILES is a list of files to search for macros and is used by pre-defined macro getmacros. If -macro macroFile is not specified, MACROFILES will have default value vector("Path/MACANOVA.MAC","Path/TSER.MAC","Path/DESIGN.MAC") where Path is the complete pathname of the directory in which MACANOVA.EXE resides. Thus using -macro C:\DATADIR\MYMACRO.MAC would cause getmacros to search for macros in the four files C:\DATADIR\MYMACRO.MAC, Path\MACANOVA.MAC, Path\TSER.MAC, and Path\DESIGN.MAC, in that order. See help topics getmacros and addmacrofile. Even if -data or -macro is not used, you can modify the default values of DATAFILE and MACROFILES by putting lines such as the following in the initialization file MACANOVA.INI: addmacrofiles(vector("C:/DATADIR/MYMACRO.MAC","C:/STAT/SURVIVAL.MAC")) DATAFILE <- "C:/DATADIR/MYDATA.DAT" (Instead of '/' you could use '\\'; see below.) Screen options The permissible screen options are -l nlines and -w ncols, where nlines is 0 or an integer greater than 5, and ncols is an integer greater than 20. These set the number of screen lines and columns, respectively. The default values are 25 and 80, respectively. -l 0 suppresses pauses between screenfuls of output. Use the -l option if your screen is a different size from the default. For example, if you have a 24 line screen, launch MacAnova by 'macanova -l 24'. If CMDFILE.TXT contains MacAnova commands to do an entire analysis, macanoXX < cmdfile.txt > output.txt where XX is 'bc' or 'dj', but not 'wx' will execute the commands and save all the results in file OUTPUT.TXT. You can use any of the above options except -l and -w with MacAnova for Windows using Run on the Program Manager File menu or modifying the contents of the Command Line on the MacAnova for Windows icon. You cannot use '<' or '>' to redirect input or output with the Windows version. Stopping MacAnova You exit MacAnova by typing 'quit', 'bye', 'stop' or 'end' at the prompt, that is, for example, Cmd> quit On the Windows 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 real mode version of MacAnova (BC), control-C and control-break both interrupt the execution and bring you back to the prompt. In the protected mode version (DJ), control-C brings you back to the prompt, and control-break is ignored. In the Windows version, select Interrupt on the File menu or press control-I (this may take a while to be noticed). DOS-Specific Aspects of MacAnova Operation The non-windows versions count lines printed since the last prompt, pausing with a message when continuous output fills the screen. The number of lines printed before a pause can be set by setoptions(height:nlines) or by including '-l nlines' in the command line at startup. See help topic setoptions. The message in the real mode version (BC) is Hit RETURN to continue or q RETURN to go to next command line: The message in the protected mode version (DJ) is Press 'q' to quit, 'j' or 'n' to see next line, any other key to continue You can execute DOS commands by prefixing the line with '!' in the first position after the prompt or by using the command shell(). This is not fully operational in the Windows version. The protected mode version (DJ) can execute quite large DOS commands, while the real mode version (BC) is memory limited. When there is not enough memory in real mode, if you are lucky, an informative message may be printed, but it may simply hang. There should be no problem with simple commands in COMMAND.COM such as DIR and CD. See help topic shell. MacAnova under real mode DOS (BC) supports CGA, EGA, VGA, 8514, and Hercules graphics adaptors. MacAnova in protected mode (DJ) supports VGA and several other graphics modes; MacAnova will try to select the best mode. Saving Your Input and Text Output You can use the spool() command to record all input and output (except high resolution graphs) from an interactive run. See help topic spool. Alternatively, as suggested above, you can put all your commands in a text file, say CMDFILE.TXT and execute one of the non-Windows versions non-interactively by macanoXX < cmdfile.txt > output.txt where XX is 'bc' or 'dj. All the commands and text output will be written to OUTPUT.TXT. Saving Graphics In the Windows version, you can use Copy on the Edit menu to copy a graphics window to the clipboard. You can switch to another program and paste the graph there. You can print the graph by selecting Print on the File menu. Saving graphics in the DOS versions of MacAnova is a bit of a pain; here are the basic methods. First, you may use "dumb" plots, which are low resolution character plots printed to the screen like any other output. You get these plots by using the keyword "dumb:T" in your plotting command; you save them along with your other output by using the spool() command. You can make this the default by setoptions(dumbplot:T). Real mode version (BC) under Windows 3.1: You can copy a high resolution MacAnova graph to the Clipboard by pressing ALT-PrintScreen while the MacAnova plot is on the screen. You then should paste the Clipboard into Paintbrush or WordPerfect or some other program that will print the image. You may wish to reverse the colors so that the plot is black on white instead of white on black. Accomplishing this depends on what program you paste the plot into. Protected mode version (DJPP) under DOS: You can copy a high resolution plot into a file by using "screendump:filename" as a keyword phrase in your plotting command, e.g. plot(x,y,screendump:"plot1.pcx"). This writes file PLOT1.PCX containing the plot in PCX format. Many programs (including Paintbrush and WordPerfect) can import the PCX format into documents. In addition, there are a number of shareware and/or commerical "screengrabber" programs. These are usually TSR (Terminate and Stay Resident) programs similar to GRAPHICS.COM that you must execute prior to starting MacAnova. Then, when the plot is on the screen, you press some combination of keys to print the plot or save it to a file. A few public domain or shareware grabbers are in the archive SCRNGRAB.EXE, but we have never had much success with them. SCRNGRAB.EXE is a self extracting archive containing several shareware TSR programs for screen grabbing or printing. It contains the following files: PRTSC.COM (a screen dumping TSR, replacement for GRAPHICS.COM, works to Epson printers) PRTSC.DOC (documentation for the preceding) LJVGA.COM (a screen dumping TSR for HP Laserject printers) LJVGA.DOC (documentation for the preceding) VGACAP.COM (a screen capture TSR) VGAFIL.EXE (a utility to translate the captured screens to other formats, such as Windows bitmaps) VGACAP.DOC (documentation for the preceding) BRUN41.COM (a utility needed for VGAFIL.EXE) VGARGSTR.DOC (registration document for VGACAP/VGAFIL) Finally, you may save PostScript commands for plots by using the keyword phrase file:"filename" in the plotting command. The PostScript file may then be printed on a PostScript printer. File or Path Names in MacAnova under DOS/Windows When you specify a "path" as a file name on such commands as vecread(), matread(), and matwrite(), you can use '/' instead of backslash ('\'). If you prefer to use backslashes, they must be doubled. Thus to read from file C:\DATA\JWDATA, you can specify "C:/DATA/JWDATA" or, since case is ignored in DOS filenames, "c:/data/jwdata". Using a double backslash these would be "C:\\DATA\\JWDATA" and "c:\\data\\jwdata". Exporting Data For Use by Other Programs In the Windows version, the easiest way to export data is using the Clipboard. Cmd> toclip(x) save REAL variable x on the Clipboard. You can use Paste on the Edit menu in other programs such as Microsoft Excel or a word processor, to retrieve the information from the Clipboard. Macro toclip makes use of special variable CLIPBOARD which is "connected" to the Windows Clipboard. See help topic 'clipboard. In any version, you can export REAL matrix x to a file that can be read by many other programs, including most spreadsheet programs, by Cmd> matprint("",x,header:F,sep:",",new:T,nsig:17) or, Cmd> matprint("",x,header:F,sep:"\t",new:T,nsig:17) The first separates fields by commas and the second by tabs. MISSING values will be written as -99999.9999. You can specify some other value for MISSING, say -99, by keyword phrase 'missing:-99'. Retrieving Previously Typed Commands In the Windows and protected mode DOS versions, you can retrieve previously typed commands for editing and re-execution, although it is done somewhat differently. In the Windows version, Edit menu items Up History (F7) and Down History (F8) insert previous commands. In the protected mode DOS version, pressing the Up-Arrow and Down-Arrow keys does the same. You cannot retrieve previously typed commands in the real mode DOS version (BCPP). Importing Data From Other Programs In the Windows version, the easiest way is using the Clipboard. In a spreadsheet program such as Microsoft Excel, select a column or other rectangular area of numbers you wish to import into MacAnova, and select Copy on the Edit menu. In MacAnova you can create a REAL vector containing all the data by Cmd> x <- fromclip() If the area Copied has m columns, say, you can create a matrix with m columns by Cmd> x <- fromclip(m) For this to work there should be no empty entries in the table being copied. Macro fromclip makes use of special variable CLIPBOARD which is "connected" to the Windows Clipboard. See help topic 'clipboard. In addition, MacAnova can read data in plain text (ASCII) files. Most programs, including Microsoft Excel, allow the option of writing a text or ASCII file. See help items vecread() and readcols for information on how to read such files. Memory Use The real mode version (BC) of MacAnova is overlayed so it requires much less RAM memory for code than its size would imply. DOS (and Windows, if running) itself takes up some space, how much depending on options, buffers, TSRs, etc. Everything that is left over can be used for MacAnova variables including pre-defined macros and variables. If there are a lot or TSRs running there may not be much room for doing things in MacAnova. Real mode MacAnova does not use extended or expanded memory. For analyzing large data sets, either the protected mode or Windows version is required. Happy Computing! Gary W. Oehlert gary@umnstat.stat.umn.edu Christopher Bingham kb@umnstat.stat.umn.edu Department of Applied Statistics 1994 Buford Ave. St. Paul, MN 55108 April 15, 1997