(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 1996, 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) 1996 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 and a modifed GO32 dos extender. Source and executable for DJGPP can be retrieved via anonymous ftp from oak.oakland.edu (in pub/simtelnet/gnu/djgpp); modifications to GO32 and the DJGPP library used here can be retrieved via anonymous ftp from umnstat.stat.umn.edu (in pub/macanova/dos/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.03 represent substantial improvement over 3.12, including many new functions and features. MacAnova was originally developed for the Macintosh(tm) computer; Unix(tm) and DOS versions are now available. The MacAnova home page is http://www.stat.umn.edu/~gary/macanova/macanova.home.html Documentation for MacAnova There are four basic sources of documentation for MacAnova: the on-line help included with MacAnova, a mostly up-to-date introductory document, a nearly complete User's Guide for Version 4.03, and a full (but somewhat out-of-date) User's Guide for Version 3.11. 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. "An Introduction to MacAnova," School of Statistics Technical Report #600, revised September 1995 is available at the University of Minnesota as a course packet for several Statistics Courses. It is also available as PostScript file Intro.ps; you may retrieve Intro.ps via anonymous ftp from the URL ftp://ftp.stat.umn.edu/pub/macanova/docs/Intro.ps You should be able to print Intro.ps on any PostScript printer. We are working on a User's Guide for Version 4.03, and we have preliminary (nearly final, really) versions ready for most chapters. These chapters are in the Adobe PDF format, which is a binary format that can be read (and printed and searched) using the Acrobat Reader software available for free from Adobe (http://www.adobe.com). Chapters 1-6 and 8 can be accessed directly over the web from the MacAnova home page (http://www.stat.umn.edu/~gary/macanova/macanova.home.html). You can also retrieve the manual via ftp from ftp://umnstat.stat.umn.edu/pub/macanova/manual and then view it offline using Acrobat Reader. A Manual for Version 3.11 is available as "MacAnova User's Guide" by Gary W. Oehlert and Christopher Bingham. It was originally issued as University of Minnesota School of Statistics Technical Report #493, revised March 1993. This does not include information on enhancements in Version 4.03. This manual is available from St. Paul Bookstore University of Minnesota 1420 Eccles Avenue St. Paul, MN 55108 It sells for about $8.50. 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. See file CHANGES.TXT for a summary of enhancements to MacAnova that are not descirbed 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 From here, you can reach all files. They can also be retrieved by ftp from ftp.stat.umn.edu/pub/macanova. Directories mac, dos, aux_file and src include files for Macintosh versions, Dos/Windows versions, auxilliary text files and source. Directory manual4.0 contains pdf forms of chapters as they are ready. 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. Installation instructions for MacAnova are in the file INSTALL.TXT. 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 -m C:\DATADIR\MYMACRO.MAC would have getmacros search for macros in 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: MACROFILES <- cat("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' 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. 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-break usually interrupts the program and brings you back to the prompt. During certain matrix operations you may have to wait a while before control-break is noticed. Control-C is ignored (though it flushes some I/O buffers). In the Windows version, select Interrupt on the File menu or press control-I. This, too, 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() or by option -l nlines 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 yet possible 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. 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). When running the real mode version (BC) under Windows 3.1, you may 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.) When running the protected mode version (DJPP) directly under DOS (but not at the DOS prompt under Windows 3.1), you may 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. 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 January 27, 1997