Frozen Fish 1: Amiga

home *** CD-ROM | disk | FTP | other *** search

/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d5xx / d572 / multiplot.lha / Multiplot / Docs / MultiPlot.doc < prev next >

Wrap

Text File | 1991-12-22 | 72KB | 1,456 lines

MULTIPLOT XLNe © A Baxter, T Mooney, 1987-1991. These programs are available for free* distribution. This program is now SHAREWARE. All rights to the source code, programs and text belong to, and copyrights are held by, Alan Baxter and Tim Mooney. DISTRIBUTION CONDITIONS SPECIFICALLY EXCLUDE REDISTRIBUTION FOR PROFIT. September 1, 1991 Immunobiology Laboratory, Massachusetts General Hospital, MGH East, Bldg. 149, 3rd Floor, 13th Street, Charlestown, MA 02129 This is the 5th version of Multiplot XLN. It is expected to receive distribution via the Fred Fish freely distributable software library. HISTORY Multiplot was originally written by Tim Mooney as a plotting utility for use with mCAD, his freeware CAD program. It supported a flexible input textfile format, many plotting options, and HPGL plotter output. It was not an intuitive program, and its full power was difficult to realize. It was also very limited in output formats and had no support for printers. Some of these problems were addressed in PLOT, an intuition interface which created an environment from which Multiplot and a collection of conversion files could be called. However the major problem of a non-intuitive way of selecting plotting options remained (the "How to Plot" window), and it was not possible to print output from within the program. Multiplot XLN resolved these problems and over three years and five releases has evolved into a powerful data plotting program with publication quality output. Tim Mooney's original code has now been completely replaced, but his work is reflected in the program structure, concept, and some aspects of the user interface. Multiplots have now been published in refereed scientific journals and presented in international scientific meetings in three continents. DISTRIBUTION CONDITIONS Multiplot is not in the public domain. It is now (from XLNe) shareware and a shareware fee of USD $20 or AUS $25 is requested. The shareware fee entitles the licensee to the most recent version of Multiplot, free support, bug fixes and source code. In addition, the licensee is entitled to one subsequent major upgrade for a reduced fee (USD $5, AUS $7, including postage). Multiplot may be freely distributed, but not included in a commercial package, commercial compilation collection, or sold, traded, leased or hired in any form or on any media without express consent of the author. It is periodically released to Mr Fred Fish, who is licensed to distribute it in any form he sees fit providing the distribution package contains documentation and examples. This package may then be compressed and posted on any electronic distribution service. Specifically, inclusion of Multiplot on commercial software compilation collections which are sold for profit is forbidden and breeches will be pursued with a tenacity rarely seen. These programs are in no way designed or intended for professional use. Any damages or losses resulting from inappropriate application of any or all of this distribution whether accidental or intentional, are not the responsibility of the authors, their wives, agents, mothers or labradors; and should not, under any circumstances, be compounded by attempting long and fruitless legal action. All rights to the source code and programs are reserved. Modifications may be made to the source code for personal use to suit local requirements, but should not be widely distributed. We would very much like to see such modifications to consider inclusion in the generally distributed version. The inclusion of the PLT: device with Multiplot in no way implies any change in, or affects the distribution conditions of that package. Please read the documentation provided with PLT: for further information. SUMMARY Multiplot XLN is a fully intuitive data plotting program. It plots data points as (x,y) coordinates with or without error bars. It can plot an unlimited number of sets of any number of data points using colour, line type, point shape and point size to represent the different sets. A set may be joined by a line or plotted as discrete points. Data may be scatter plotted, or shown as a histogram or step graph. Additions to the data may be made in the form of lines of best fit (logarithmic, exponential, linear and polynomial) and data smoothing utilising modified open b-splines or averaging filtration. The input file for multiplot is a simple textfile and my be created in the NotePad or saved from any spreadsheet. Multiplot fully supports the clipboard, and data input may be achieved solely through it. Output may be in any of the following formats: IntroCAD, Draw, mCAD, IFF, Revised Hewlet-Packard Graphics Language (HPGL/2), Encapsulated Postscript (EPSF) or Postscript. The graph can be printed to any workbench printer by transparent use of the PLT: device. Multiplot directly supports Postscript laser printers such as the Apple Laser printer; and the HP LaserJet III. REQUIREMENTS * Workbench 1.3 (or higher) including: Maths libraries, assignment of ENV:, T:, and CLIPS:. The C: directory must contain the files c:run, c:failat c:mount and c:type. * The PLT: device is necessary for printing. It consists of: - Plt-handler in the l: directory - The mountlist entry for plt added to the devs:mountlist - Assignment of the PLTDATA: directory containing PLT fonts. * At least 1/2 Mb RAM. * The directory which contains Multiplot must contain a subdirectory called "MPlot_support" (without the quotes) which must contain the files "intro.scn", "txt_2_icad", "plot2draw" and "HPGL2PS" (without the quotes). * The file MPlot.def should either be in the "MPlot_support" directory, or in the S: directory. * The font Topaz.11 is used for all screen text. Topaz.11 should be placed in the WB1.3 Fonts: directory. Note that this is unnecessary with WB2.0 because it is in ROM. INPUT FILE FORMAT Multiplot accepts a simple ASCII file for input of data. This file may be written on any text editor, including the NotePad, or may be generated as a textfile from a spreadsheet. Multiplot does not choke on the linefeed/carriage-return of IBM style spreadsheets. The data must consist of columns of numbers and need not contain text. Text heading the file will be ignored and may be used for an explanatory note. Lines beginning with the text below are of special significance: *TITLE* Text will be used for a title (optional). *XLABEL* Text will be used for a label on X axis (optional). *YLABEL* Text will be used for a label on Y axis (optional). *LEGEND* The text will be used as a label for the following data set (optional). *SCALFACT* The key word should be followed by the same number of values as there are columns of data in the file. The numbers in each column will be multiplied by the *SCALFACT* value in the respective column. (optional). *AUTOSCRIPT*, *XAXISDATA* and *YAXISDATA* are reserved keywords that indicate the file has been written by Multiplot. They should not be used in import files. (*AUTOSCRIPT* is a trademark of BioSoft Pty Ltd.) *EXTRATEXT* is a reserved keyword that indicates that arbitrary text and its placement has been written by Multiplot. It should not be used in import files. Note that *LEGEND* and *SCALFACT* can be used repeatedly through the data file. Blank lines or lines of text interrupting the columns of numbers are interpreted as separating sets of data, and each set will be plotted individually in, for example, a different colour or point size. See "plotme.dat" or "eric.dat" for examples of input file format. STARTING OUT From the CLI: multiplot [-O] [-B#] [-I] [filename] Type 'multiplot' with or without the filename of the input data file. If a '?' is used as an argument, a simple description of usage is given. The '-O' option will prevent an overscan screen being opened. This option will have no effect if you are not using an overdimensional workbench. The I option will result in a non-interlaced screen instead of the default, a hires-interlaced screen. The B option will set the number of bitplanes for the screen. The # value must immediately follow the B and may be one of 1->4. The default value is 3. The number of bitplanes affects the number of on-screen colours as follows: 1 bitplane ---> 2 colours 2 bitplanes ---> 4 colours 3 bitplanes ---> 8 colours 4 bitplanes ---> 16 colours For example, the following are valid invocations of Multiplot: Multiplot -O -B1 plotme.dat (Autoloads named file into a 2 colour screen with no overscan) Multiplot -O -B1 -I eric.dat (Autoloads named file into a 2 colour non-interlaced screen with no overscan) Multiplot -B2 plotme.dat (Autoloads named file into a 4 colour screen with overscan if Workbench is overscanned ) Multiplot -B3 -O plotme.dat (Autoloads named file into a 8 colour screen with no overscan) Multiplot -B4 (Starts Multiplot with file requester and a 16 colour screen with overscan if Workbench is overscanned) Multiplot (Starts Multiplot with file requester and an 8 colour screen with overscan if Workbench is overscanned) Multiplot must be started either from within its own directory, or by including the file path from the current directory. It cannot be invoked by adding it to a default command path like the C: directory. This limitation may be overcome by the use of the alias command. eg: alias Multiplot "dh0:<path>/Multiplot -O" From the Workbench: Double click on the Multiplot icon OR Edit your input file in a simple editor (NotePad will do fine), and save with an icon. You can then change the file's default tool (INFO from the left hand Workbench menu) to Multiplot:Multiplot or whatever the file path is. Multiplot will then be automatically invoked when the file is double clicked. An alternative to this is to not change the file's default tool, but to click on the file to highlight it, hold the shift key down, and then double click on the Multiplot icon. OVERSCAN SCREENS If you are using an overscan WorkBench (via MoreRows or the WB2.0 preferences setting) Multiplot will attempt to open a screen the same size as your workbench screen. This enables you to make the most of the resolution of your monitor. It is not usually possible to open a 16 colour interlace high resolution screen with overscan unless you have 1Mb chip ram. The maximum overscan available is 724 x 566 on a PAL machine or 724 x 482 on an NTSC machine. If the WorkBench overscan exceeds these values a default size screen is opened. It is important to note that on machines, some saved preferences result in a screen that requires too much bandwidth to be supported by a standard Amiga. In this event the display may be truncated or rendering affected. Providing the dimensions of the workbench screen are less that those above and the machine has 1 Mb chip ram, this may sometimes be corrected by quitting the program, and shifting the workbench screen to the left in the screen location setter in the preferences program. In the event of difficulties with overscanned screens, disable Multiplot's overscan option. The default to overscan can be prevented in three ways: 1) Use a standard Workbench. 2) If starting from the CLI, use the -O option as the first argument. 3) If starting from the workbench, set the TOOLTYPES string in the info requester for the Multiplot icon to "OVERSCAN=OFF" (without the quotes). If the system has little chip ram or it is greatly fragmented, Multiplot may be unable to open a screen at all. In this case, you will see an "Insufficient Memory" warning and the program will quit. Close extra windows, quit unneeded programs, and try again. If chip ram is badly fragmented, you will need to reboot. SCREEN MODE Multiplot is designed to be run on an interlaced screen. Occasionally it may be desired to run Multiplot on a non-interlaced screen. This may be achieved by either using the CLI argument '-I', or adding the tool type 'MODE=HIRES' to the Info requester for the Multiplot icon. Please note: * The vertical stretching of the buttons in the requesters results in some confusion, especially of the orientation button in the Print Setup window. * The default fonts should be altered to a non-proportional (fixed width) font suited for non-interlace screens. This can be achieved by editing the mplot.def file as described below. MEMORY CONSERVATION Multiplot can be used successfully on Amigas with 1/2 Mb RAM or 1/2 Mb chip ram if care is taken to conserve memory. The following measures should be used either separately or together, depending on requirements: 1) Assign T: to a disk, not RAM. Multiplot uses the T: directory to write temporary files. 2) Assign CLIPS: to a disk, not RAM. Multiplot uses the CLIPS: directory to store data pasted to the clipboard. 3) Do not have the default plot fonts (set by the Mplot.def file) in the FONTS: directory. If they are absent, Multiplot will use the screen default font. If using WB1.3, do not have Topaz.11 in the FONTS: directory. Then Multiplot will use the Topaz.8 ROM font. 4) If starting from the CLI, use the -O option as the first argument. This will prevent Multiplot opening an overscanned screen. 5) If starting from the workbench, set the TOOLTYPES string in the info requester for the Multiplot icon to "OVERSCAN=OFF" (without the quotes). This will prevent Multiplot opening an overscanned screen. 6) If starting from the CLI, use the -B option to reduce the number of bitplanes used for Multiplot's screen. This is important for machines with 1/2 Mb Chip RAM. 7) If starting from the workbench, set the TOOLTYPES string in the info requester for the Multiplot icon to "BITPLANES=#" (without the quotes). If # is less than 4, Multiplot will open a screen with fewer colours. This is important for machines with 1/2 Mb Chip RAM. 8) If starting from the CLI, use the -I option to open a noninterlaced screen. 9) If starting from the workbench, set the TOOLTYPES string in the info requester for the Multiplot icon to "MODE=HIRES". If Multiplot is run on a PAL Amiga with a noninterlaced, non overscanned, 1 bitplane (2 colour) screen, it uses 110 Kb before loading data, and 160 Kb after loading a moderately large data file. PHILOSOPHY OF THE USER INTERFACE Multiplot fully supports the Amiga's graphical user interface. Below are listed a few of the important features of this interface that relate to the use of Multiplot. 1) An item is a pictorial representation of something on the screen. 2) An item to be worked on is first selected, and then the desired action is performed. 3) An item may be selected by moving the mouse pointer over it and clicking the left mouse button. This action will highlight, change or place a box around the item to indicate that it has been selected. If the item is a button ("gadget"), selecting it may invoke some specific action. If this is the case, the picture on the item should give some idea of what the action is. Multiplot makes extensive use of buttons that indicate the status of a selection. For example, the line type button has as its picture the type of line currently in use. Selecting this button will change the picture and the line type to another choice. Note that the points of a data set are items, but the joining lines are not; thus a data set can only be selected by clicking on one of its points. Multiple items can be selected together by selecting one, pressing and holding down the shift key, and selecting the rest. This is called "group selection". 4) Special activity relating to an item may be started by placing the pointer over it and clicking the left mouse button twice in rapid succession ("double clicking"). In Multiplot, this action will usually open a special window allowing you to edit characteristics of the selected item(s). 5) Some other actions which may be performed on the selected item(s) may be found in the menu bar. These may be selected by placing the pointer over the title bar at the top of the screen and pressing and holding down the right mouse button while moving the over the selections that drop down from the title bar. A selection is made by releasing the right mouse button over a selection, or by clicking the left mouse button. Multiple selections can be made by clicking the left mouse button over each of the desired options before releasing the right mouse button. 6) Some items are movable. An item may be moved by placing the pointer over it and pressing and holding down the left mouse button while moving the pointer to the new location. This is called select-dragging. Only text and data points may be moved in Multiplot. Multiple items can be select-dragged by group selecting them first. Items can be dragged up/down with out sideways movement by holding down the 'v' key while dragging. Items can be dragged sideways without vertical movement by holding down the 'h' key. 7) The delete key will remove item(s) that have been selected. The item(s) may be retrieved by selecting Undelete from the EDIT menu. Only text, data points and whole data sets may be deleted from Multiplot. 8) The escape key will quit the program, or if a special window is open, will quit the window without changes. 9) The return key will allow continuation of work, will proceed to the next selection, or will accept changes and implement them. It will cycle through available text edit boxes in a window, activating each in turn and will not quit a window while a text edit box is currently activated. Once all the text boxes have been edited and deactivated, then hitting return again will continue by quitting the window. THE DATA SELECTION WINDOW After being started, Multiplot tries to work out whether it is on a PAL or NTSC machine, and opens a screen of the appropriate size. If an overscan workbench is used, a screen as large as possible up to the size of the workbench screen will be opened. The screen's palette is read from the file "MPlot.def" which should be in either the same directory as Multiplot or the s: directory. If it is not found, you will be informed and a screen the colour of vomit will be opened. This should encourage you to save a new default palette! The next thing you may see is the DATA SELECTION WINDOW. If you started Multiplot by telling it what file you wanted to plot, the file's name will be in a little box. If Multiplot is invoked without telling it what file you want, the default file name will appear in the box. The PATH button will call up a file requester to help with browsing directory trees looking for wanted data files. The NONE button will clear the file name. If you continue plotting without a file name, a blank plot window will be opened into which clipboard data may be pasted. Beneath the file selection box are four other boxes to indicate what column the X, Y and Error values are in. A '0' indicates values are absent. For example if the Error box has a '0', no error bars will be plotted. If the X box has a '0', the X values will be assumed to start at 0 and increase by 1 with each data point. If the Low Error box has a '0' but the Error box does not, the error bars will be assumed to be symmetrical about the data point. If however, the Low Error column is defined, asymmetrical error bars may be plotted. When satisfied with the file and column specification, hit the return key or click on the Continue=> arrow. The selected data file will be checked to ensure it has the number of columns required, and loaded if suitable. If the file you identified when invoking Multiplot has previously been written by Multiplot, it will autoload without presenting you with the DATA SELECTION WINDOW. THE PLOT WINDOW The PLOT window fills the entire high resolution screen and contains a hand crafted menu for your computing pleasure. Visible on the window will be a default plot of your data. This plot will show lines and points with a different colour and point type for each data set. The PLOT window contains 5 regions. The central area is where the data is represented. The left margin contains the Y values and Y axis label. The right margin contains the legend. The lower margin contains the X values and the X axis label and the top margin contains the title. On starting Multiplot, the pointer action is set to SELECT. In this mode it is possible to select objects to alter their characteristics. A data set may be selected by clicking the left mouse button near one of its points. A legend may be selected by clicking the left mouse button on it. In this mode, double clicking on an object will call up window to change some feature of the object. Double clicking on a point in a data set will call up the CUSTOM PLOT window, and allow you to change line type, colour, point type and point size of the data set. It will even allow you to skip rendering that set or delete it completely. Double clicking on a legend will call the EDIT TEXT window, to allow you to edit the text in the legend. Double clicking in the top margin will call up the EDIT TEXT window to allow you to edit or add a title. Double clicking in the bottom or left margin calls up the X AXIS or Y AXIS windows, which allow you to set the minimum and maximum tic values, the number of tics, and edit the axis label. Double clicking on an axis value allows you to edit the text of that value. This text will be reset on rescaling the axis unless the axis values lock is set in the AXIS window. In the SELECT mode, it is possible to move text around the screen by pressing the left mouse button while the pointer is over the text, holding it down, and dragging the text to the desired location. If the movement is small, a screen refresh may need to by forced by selecting the menu option ACTIONS/Redraw. Several blocks of text can be moved together, without changing their relationship to each other by group selecting them. Click on one block of text, hold down the shift key and select the others, then without releasing the left mouse button, drag the blocks of text to their new location. To move text vertically without any horizontal movement, select (or group select) the text, and while still holding down the left mouse button, press and hold down the 'v' key on the keyboard. Then drag the text to its new location. To move text horizontally without any vertical movement, select (or group select) the text, and while still holding down the left mouse button, press and hold down the 'h' key on the keyboard. Then drag the text to its new location. Single data points can be moved in a similar manner. To select a data point, click the left mouse button near it while holding down the Ctrl key. Several data points may be group selected by holding down the shift key as well as the Ctrl key while selecting the points. To move data points vertically without any horizontal movement, select (or group select) the points, and while still holding down the left mouse button, press and hold down the 'v' key on the keyboard. Then drag the points to their new location. To move points horizontally without any vertical movement, select (or group select) the points, and while still holding down the left mouse button, press and hold down the 'h' key on the keyboard. Then drag the points to their new location. Multiple items of different natures may be group selected together. It is possible to select whole data sets, single points and text in one go. Note however that only data points and text can be moved. A curve reader is also available in the SELECT mode. If the Alt key is held down when the left mouse button is pressed, the coordinates of the point indicated will be given. The curve reader automatically compensates for log axes, zooming and sliding. The pointer action can be set to ZOOM or SLIDE by selecting these subitems from the Pointer Action option in the EDIT menu. The action of the pointer in these modes is described below. The menus available are PROJECT which relates to the loading, saving and printing of plots, EDIT which allows you to delete, copy, paste, import and export data and text, ACTIONS which allows modification of the plot, resizing, shifting and zoom, OPTIONS which changes the screen palette, changes the axes, grid and cross hair on or off, and FUNCTIONS which allows special actions like data smoothing, line fitting and data sorting. The major menu selections are described below. TEXT IN MULTIPLOT Multiplot supports three kinds of text: Operator independent, operator semidependent and operator dependent. ** Operator Independent Text The title, X axis label and Y axis label are operator independent. Their text is rendered in a preset position and cannot be moved. Their content can be edited by double clicking on them. ** Operator Semi-Dependent Text The legends and axis values are operator semi-dependent. They are created in a default position but may be moved by select-dragging and edited by double clicking. The legends are created with a small line in the relevant colour/line-type to their left and are placed in the right margin which is sized to fit them in an aesthetically pleasing manner. The axis values are a special type of Operator Semi-Dependent text. In general, Multiplot tries to update the axis values as you change the characteristics of your graph. For example, if you zoom in or out, Multiplot will replace the axis values with new values. If you decide to toggle the right margin, Multiplot will move the axis values with the associated tic mark to the correct position on the axis. These alterations may not be desired, and may actually move or change the text of a lovingly edited axis value. If you _do not_ wish Multiplot to move or update your axis values, turn the Axis Values Lock ON, either by the OPTIONS/Lock menu or by calling up the edit Axis window (double click the left mouse button over the axis). ** Operator Dependent Text Any text added to enhance a plot (arbitrary text) must be dragged to the desired location by the user. It can be edited or deleted in the normal manner. FONTS Text representation in Multiplot is complicated by the bit mapped nature of the Amiga fonts. Multiplot handles graphics by vector mapping. That is, it draws lines by deciding on a starting point and an end point and joining them with a line of the highest resolution it can. This is why it manages to support CAD and DTP programs through its various output formats, why it can draw to a screen of any size, and why its printed output looks so smooth. The Amiga fonts are bit mapped. That is rather like drawing by colouring in the squares of a crossword puzzle. Multiplot has to try to cope with the inability of Amiga fonts to scale or provide satisfactory printed output. As a result, Multiplot maintains two "layers". The lower layer is scalable and contains the data points, lines, axes, tics and error bars. The upper, superimposed layer is the bitmapped layer in which the Amiga fonts reside. This layer does not scale. On screen text in Multiplot represents the actual location and size of printed text as a proportion of the graph's overall dimensions. The printed font used is the HP-GL default font, which is similar to Courier. On screen, this font may be represented by any mono-spaced font, and Courier is used if present in the Fonts: directory. Otherwise the default topaz.9 is used. A font requester will be added in the forthcoming OS/2 version of Multiplot. It is possible to alter the default fonts that Multiplot attempts to open on startup. Indeed this should be done if it is desired to run Multiplot on a non-interlaced screen. Note that proportional fonts are not supported, and currently print erratically. Topaz or Courier work well. The default fonts are listed in the file mplot.def which is read at startup. At the bottom of the file is something like the following: Courier.font 13 <--- X axis text font Courier.font 13 <--- X values font Courier.font 13 <--- Y axis text font Courier.font 13 <--- Y values font Courier.font 24 <--- Title font Courier.font 13 <--- Legends & extra text font The font name or size can be altered using any simple text editor (Notepad will do). Multiplot will then attempt to load the new fonts and sizes on startup. MULTIPLE GRAPHS IN MULTIPLOT The Plot window allows editing of a single graph at a time. Multiplot does allow the editing of multiple graphs at the same time by using a "virtual page" system. Each time a new graph is started using the PROJECT/New Graph menu option, the Plot window displays the new data while maintaining in memory the pre-existing graphs. Graphs can be swapped by selecting the PROJECT/Swap Graph menu option. If more that 2 graphs are in memory, a requester will ask for the graph number to swap to. Each graph maintains its own Print Setup window which controls where on the printed page its graph will appear, what size it will be, and which orientation (portrait or landscape). On selecting PROJECT/Print each graph in memory will be printed according to its own print setup on the same page. While the page is in memory it is referred to as a virtual page, because although it exists only in memory, it is possible to draw on it as one might on a real page. The virtual page can be viewed by choosing the PROJECT/Print Preview menu option. In addition to printing, file saves in Postscript, Encapsulated postscript and HP-GL support the virtual page, and will write files describing all graphs in memory. IFF, IntroCAD and Draw saves only save the currently active graph which is the one visible in the Plot window. THE PROJECT MENU OPEN FILE (Right-Amiga O) Returns you to the DATA SELECTION window for loading a new file. ADD FILE Opens the DATA SELECTION window for loading a new data file. All data sets and text described in that file will be added to the current graph. NEW GRAPH Opens the DATA SELECTION window for loading a new data file, which will be loaded onto a fresh graph, while maintaining the old graph in memory. SWAP GRAPH Swaps between the graphs currently in memory. Has no action if only one graph loaded. CLOSE GRAPH Closes the current graph without quitting the program. If there are no other graphs loaded in memory, will open the DATA SELECTION window to select a new graph. SAVE (Right-Amiga S) Saves data, formatting and text as a Multiplot file, overwriting original data file. SAVE AS Plots may be saved in any of the following formats: IFF (loads into DPaint), Draw (loads into Draw2000 etc), IntroCAD (an excellent CAD program), mCAD (a PD CAD program), HPGL plotter language, Encapsulated Postscript and Postscript. Please note the following restrictions: Currently Draw, IntroCAD, and mCAD saves do not include the numbers or labels on axes. This is because of the lack of font support in these programs. Draw saves require the program Plot2Draw to be in the same directory as Multiplot. IntroCAD saves require the program Txt_2_Icad to be in the same directory as Multiplot. EPSF and postscript saves require the program HPGL2PS to be in the same directory as Multiplot. Also note: # Neither Professional Page nor PageStream handle Draw files with large dimensions very well. If your dimensions are greater than 200 units, these programs often scramble the data. Rescale your data to keep within these limits if you wish to import to either of these programs. Data may be rescaled by adding a line to the data file which begins with "*SCALFACT*" and contains scale factors by which data following is to be multiplied. Scale factor columns map to data columns after the keyword "*SCALFACT*" is discarded. # Professional Page does not recognise Draw format line types. All line type information is lost in transferring Draw format plots to Professional Page. # PixelScript does not support PostScript line types. All line type information is lost when transferring postscript output to Pixel Script. # mCAD does not handle plots with small dimensions very well. If your data is in hundredths of units, mCAD will not plot anything on the screen. This can be corrected by using *SCALFACT* to rescale data. # CAD file formats are very poorly optimised. As a result, saves of large plots may take a long time. SAVE DEFAULTS Saves current font and palette selections to the file mplot.def which is read on startup. PRINT PREVIEW Print preview is achieved via the transparent use of the PLT: device. The plt-handler must be in your l: directory, and the PLT: mountlist must be added to your DEVS:mountlist. You do not need to mount the device. Multiplot will mount PLT: automatically if it is not already mounted. PRINT SETUP Opens the Print Setup window which allows the selection of print orientation, size and position on the page. The print spooler can be toggled on or off from this window. PRINT (Right-Amiga P) Printing is achieved via the transparent use of the PLT: device. The plt-handler must be in your l: directory, and the PLT: mountlist must be added to your DEVS:mountlist. You do not need to mount the device. Multiplot will mount PLT: automatically if it is not already mounted. Notes on use of Plt: # Plt: opens its own window on the workbench when it starts up. This window relays information about how much of the image has been printed and the remaining system memory. It also provides a "close gadget" (The square with a dot in it for closing windows) which will abort the print. Use the left-Amiga-M and left-Amiga-N key combinations to switch between Multiplot's screen and the workbench. This will be corrected in a future release of Plt:. # Multiplot checks for the presence of the Plt-handler in the L: directory before attempting to mount Plt:. If this file is not present, Multiplot will not print, even if the Plt: device has been mounted by some other mechanism. # The Plt: device checks the print resolution requested in preferences. If you want the nicest possible quality print-outs from Multiplot, set your printer density setting (graphics screen 2) to "7". # Plt: currently has a bug which prevents it from handling two tasks simultaneously. Do not attempt to print preview while printing or print two files at once. QUIT (Right-Amiga Q) Quit exits the program without saving any changes. THE EDIT MENU UNDELETE (Right-Amiga Z) Replaces the last blocks of text or data sets deleted. Only a single level of undelete is maintained, but it may contain multiple items if, for example, several data sets were group selected and deleted. COPY (Right-Amiga C) Places a text version of the selected data sets or text blocks in the clip board for transfer to another plot or program. PASTE (Right-Amiga V) Reads the clipboard. If the clip has been written by Multiplot, it will be added to the current graph. If it consists of 2 columns of numbers, the first column will be assumed to be X values, and the second, Y values. If there are 3 columns, the third will be assumed to be error-in-Y. Blank rows are interpreted as end/beginnings of data sets. Legends and text can also be read, if they conform to the flat file data format described above. CUT (Right-Amiga X) Places a text version of the selected data sets or text blocks in the clip board for transfer to another plot or program, and then deletes it from the current plot. DELETE (Delete key) Removes data set(s) or block(s) of text currently selected. THE ACTIONS MENU MOUSE ACTION Allows the user to select the mode in which the mouse works. The options are Select, Zoom and Slide. Select (Right-Amiga-Shift !) The select mode allows the editing of data sets or axes by double clicking the left mouse button over them. This action calls up a window for editing their characteristics. This mode also allows the movement of text by click-dragging, and selection of text or data sets for manipulation. It is possible to select multiplot data sets my selecting one set, and holding down the shift key while selecting the other sets. The same method can be used to group select text. Zoom (Right-Amiga-Shift #) Allows closeup views of areas of the data, and to adjust the axes to desired values. After selecting ZOOM from the menu, the mouse may be used to draw a box on the screen to indicate the area of the plot to be enlarged. This is achieved by clicking and holding the left mouse button, dragging the mouse, and releasing the left mouse button. The maximum limit of enlargement is 1,600 times. Zooming out to reduce the size of the plot by one half is achieved by double clicking the left mouse button. Slide (Right-Amiga-Shift ^) After selection the mouse may be used to draw a vector on the screen to indicate the direction and amount the plot should be moved. This is achieved by clicking and holding the left mouse button, dragging the mouse, and releasing the left mouse button. AXIS SCALE LOCKS Allows either the X or Y dimension to be frozen while the other is zoomed or rescaled. very useful when used in conjunction with the other items in this menu (Zoom, Slide, FullPlot). This allows you to arrange the scale of the plot to best advantage. The Subitem X AXIS will lock the amount of zoom in the X axis, and the subitem name will change to "X LOCK ON". The lock may be turned off by reselecting the subitem. The same applies for the Y AXIS selection. the BOTH LOCKS ON selection will lock both axes. They can be both turned off with BOTH LOCKS OFF. The amount of zoom can be manually set from the X and Y AXIS windows. Unless locked, the following options will reset the view of your data: Full Plot, Redefine Plot, Sort, Linear Fit, Smooth, Logarithmic Fit. AXIS VALUE LOCKS Allows either the X or Y axis values to remain unchanged despite rescaling of the axis. This option allows the editing of axis values to create text labels without having them moved or overwritten. REDRAW (Right-Amiga R) Redraws the screen with the same zoom as currently set. It should be used to repair the screen of unwanted rendering, or an incomplete refresh. This option is different from FULLPLOT and REDEFINE PLOT which will reset to either the full plot, or if the X or Y locks are on, to the locked plot size. FULLPLOT (Right-Amiga F) Redraws the screen with the default axis settings. This plot will show all data points and the extremes of any error bars. It will not overcome locked axis settings, so if you have defined a set of minimum and maximum axis values, it is wise to lock them with the BOTH LOCKS ON option. REDEFINE PLOT (Right-Amiga D) Presents the user with the CUSTOM PLOT WINDOW for each data set in succession. This is useful for editing all data sets, editing the characteristics of a data set plotted as a line (when it may be difficult to recognise where the points are for selection with the mouse) or if a data set has been skipped (possible from the Custom Plot window) and not plotted. This action is destructive in the sense that any zooming that has not been locked will be lost. ADD TEXT (Right-Amiga A) A legend may be added to an unlabelled data set by selecting it (single click of left mouse button near any point of the data set) and choosing this menu option. A EDIT TEXT window will appear in which the legend text may be typed. This is also another way of editing existing legends, and can be used to add arbitrary text if used without selecting a data set. THE OPTIONS MENU CROSS HAIR (Right-Amiga L) Provides a cross hair for the cursor to assist with zooming, sliding and movement of text blocks. GRID (Right-Amiga G) Allows the selection of a cross grid, tics, or no marks on the axes. AXES Allows the selection stem and leaf (left and lower axes shown), box or no axes drawn. RIGHT MARGIN (Right-Amiga M) Toggles the right margin space for legends. PALETTE The screen palette may be altered by calling the neat requester, which was written by RJ. The only non obvious feature of the requester is that by clicking the left mouse button on the RGB characters, the requester is converted to a hue/saturation/lightness requester for those who think that way. SIG FIGURES Allows the number of significant figures of axis values and formulae to be set independently. This option only applies to values calculated subsequent to its selection. To change values already on screen, it is necessary to force a recalculation. For axis values this can be achieved by selecting ACTIONS/Full Plot or ACTIONS/Redefine Plot. To alter legends of line fits, the line fit needs to be deleted and recalculated. ERROR BARS (Right-Amiga E) Toggles the error bars on and off. If a data set is loaded without error bars, and error data is added later via the EDIT POINT window, it will be necessary to select this option to get them rendered. If error bars are unimportant, this option should be turned off to speed screen refresh times. THE FUNCTIONS MENU SORT DATA This option will place the data points in order of ascending X value. This allows other manipulations of the data which require this format. SMOOTH DATA Select a data set by clicking the left mouse button near one of its points, and then select one of the subitems from this menu option. Filter A new data set will be created in which each Y value is the mean of the surrounding Y values from the original data set. A requester will appear enabling you to enter the number of values each side of the point for the mean to be taken over. This option is most suitable for smoothing data sets containing large numbers of points. This action is destructive in the sense that any zooming that has not been locked will be lost. Interpolate A new data set will be created in which intermediate data points are added to create a smooth curve tracking the original data. This option is most suitable for smoothing data sets with relatively few points. It is sometimes useful to provide intermediate points before filtering to provide a smoother curve. This action is destructive in the sense that any zooming that has not been locked will be lost. LINEAR FIT Select a data set by clicking the left mouse button near one of its points, and then select this menu option. A new data set will be created which will represent a straight line fit of the data. The formula of the line is shown in the legend. This action is destructive in the sense that any zooming that has not been locked will be lost. Note that the current axis settings are taken into account for linear fits of data. For example, if the Y axis is logarithmic and the X axis linear, an exponential fit is produced (a straight line on a lin/log scale). If the X axis is logarithmic and the Y axis linear, a log fit is produced (a straight line on a log/lin scale). Log/log and true linear fits are also available. POLYNOMIAL FIT Select data set by clicking the left mouse button near one of its points, and then select this menu option. A window will allow selection of the order of fit. High order fits may require extended calculation times. A new data set will be created which will represent the appropriate fit of the data. The formula of the line will be displayed as its legend if the is sufficient room. COMMAND KEY SEQUENCES Multiplot fully supports keyboard shortcuts using the right Amiga key. A full list of shortcuts and mnemonics is listed below: Key Command Mnemonic A not used B OPTIONS/Axes/Box <B>ox C EDIT/Copy <C>opy D ACTIONS/ReDefine Plot Re<D>efine Plot E OPTIONS/Error Bars <E>rror Bars F ACTIONS/Full Plot <F>ull Plot G OPTIONS/Grid/Grid <G>rid H PROJECT/Save as/HPGL <H>PGL I PROJECT/Save as/ILBM <I>LBM J not used K PROJECT/Save as/DrawSave <K>AD format L OPTIONS/Cross Hair Cross Hair <L>ines M OPTIONS/Right Margin <M>argin N PROJECT/Save as/IntroCAD I<N>troCAD O PROJECT/Open <O>pen P PROJECT/Print <P>rint Q PROJECT/Quit <Q>uit R ACTIONS/Redraw <R>edraw S PROJECT/Save <S>ave T OPTIONS/Grid/Tics <T>ics U OPTIONS/Screen Title <U>p the top screen writing V EDIT/Paste Commodore guidelines W PROJECT/Save as/Data <W>rite data X EDIT/Cut Commodore guidelines Y OPTIONS/Axes/X and Y X and <Y> Z EDIT/Undelete Commodore guidelines Please note that there are three other keyboard shortcuts that allow you to swap between mouse actions. These also require that the right Amiga key is held down. Shift-1 (!) ACTION/Mouse Action/Select Shift-3 (#) ACTION/Mouse Action/Zoom Shift-6 (^) ACTION/Mouse Action/Slide The Escape and Delete keys are supported: Esc PROJECT/Quit Del EDIT/Delete The Alt key is used to activate the curve reader. Holding down the Alt key while clicking the left mouse button while in SELECT mode will result in a window that displays the X and Y co-ordinates of the pointer. The Shift key activates group selection when in SELECT mode. The Ctrl key allows selection of a single data point instead of a whole data set when in SELECT mode. The 'v' key restricts movement of selected items to vertical. The 'h' key restricts movement of selected items to horizontal. THE CUSTOM PLOT WINDOW For each data set for plotting, this window can be called to allow you to select plot colours and whether data is plotted as a line, series of points, both, a histogram, or a step plot. If points are drawn, the point size and point type can be selected. If a line is drawn, the line pattern can be selected. The colour and line type are selected by repeatedly clicking the left mouse button on the buttons that represent the current selection shown at the left of the window. The number between the colour and line type buttons displays the size in pixels of points if plotted. The plot type is selected by clicking the left mouse button while the pointer is over the desired selection displayed in the middle of the window. Currently, data may be plotted as points, lines, points and lines, step graph (with or without points) and impulse plots. The step graph is of the form change in X followed by change in Y. The point type may be selected from the panel of six mutually exclusive buttons on the right of the window. The CONTINUE button will accept changes and proceed to the Plot window where the plot is rendered. The SKIP button will skip a single data set, so that it will not be plotted when the PLOT window is opened. The missing data set can be recalled by selecting the Redefine plot option from the EDIT menu, and pushing the CONTINUE button when presented with the data set. The KILL button is similar to the SKIP button but its effects are permanent. A dead data set can be revived with EDIT/Undelete. The STOP button will skip all remaining data sets without presenting the Custom Plot window for them. It will not accept changes made to the data set currently being edited. THE AXES WINDOW For either or both the X and Y axes, this window can be called by double clicking the left mouse button over the axis to be edited with the Mouse Action menu option set to SELECT mode. This window allows the following characteristics of the axis to be edited: * Minimum and maximum axis values. The axis scale may be reversed by placing the higher value in the minimum value box and the lower value in the maximum value box. This results in mirror image reversal of the data. * The number of major tics. The number of major tics may vary from 1 to 20. * The number of minor tics. The number of subdivisions may vary from 1 to 10. * Axis scale type. The axes may be set as linear, logarithmic or category independently allowing log/lin, lin/log, log/log and lin/lin plots. * Category axes are available, in which each data set is given a value along the axis resulting in a scattergram. Either the X or the Y axis may be set as a category axis, providing vertical or horizontal scattergrams. The category axis provides default values which may be altered to distinguish points which overlap each other. For example, a vertical scattergram may be produced by setting the X axis to a category axis. Two overlapping points may be separated by selecting the point (Ctrl-LMB), locking movement to horizontal (hold down the 'v' key) and dragging one point clear of the other. * The axis label. * A lock may be set preventing rescaling of the axis. * A lock may be set preventing overwriting of the axis values. Note that the current axis settings are taken into account for linear fits of data. For example, if the Y axis is logarithmic and the X axis linear, an exponential fit is produced (a straight line on a lin/log scale). If the X axis is logarithmic and the Y axis linear, a log fit is produced (a straight line on a log/lin scale). Log/log and true linear fits are also available. THE EDIT POINT WINDOW This window may be called up for any data point by holding down the Ctrl key and double clicking the left mouse button near the desired data point with the Mouse Action menu option set to SELECT mode. This window allows the X and Y values of a point to be individually set, and the error bars to be altered; either above or below the point. Note that the error bars need not be symmetrical, and one direction error bars are supported. THE PRINT SETUP WINDOW The Print Setup window is called be selecting the PROJECT/Print Setup menu option. This window allows the selection of print orientation, size and position of the current graph on the printed page. A sliding knob sets the size of the plot. Default is for the plot to fill the page. Clicking within the slider's run allows changes in size from 10% to 100% in 10% increments. Dragging the slider allows finer control of the plot size. A button controls the orientation of the plot. Default is for landscape. Orientation may be toggled between landscape and portrait by clicking the left mouse button over the icon which represents the current setting. The position of the plot on the page can be set by dragging the box representing the plot to the desired location on a rectangular field representing the printed page. The print spool may also be toggled on and off from this window. When the print spool is used, plot printing can continue as a background task, while continuing work. Once the print spool has been started, Multiplot may even be quit without interrupting printing. If it is desired that printing be ceased, this is achieved by clicking the left mouse button on the "close gadget" (top left corner) of the PLT window on the WorkBench. HINTS AND TIPS Q: What can I do to improve the appearance of the printed output on my dot matrix printer? A: One way to enhance the appearance of your printouts is to use different pen thicknesses. For example, the axes could be in a thick pen, and the grid lines in a finer pen. To achieve this, type the following line into a CLI window before printing: setenv pltinfo P/000-3/000-1/000-2/000-2/000-2/000-2/000-2/000-2/ Q: How do I get a line fit of only part of a data set? A: Group select (shift-control-select) and delete the unwanted data points. Select the set, choose the FUNCTIONS/Linear fit menu option, and select the EDIT/Undelete menu option. Q: Is there any way I can change the font size in Multiplot? A: Multiplot does not yet have a font requester. If you wish to use a different sized font (say, for photo-reproduction), ensure the desired size is in your FONTS: directory, and run fixfonts (in the Sys:system directory). Then edit the 'mplot.def' file in the MPlot_Support directory to default to the desired fonts and sizes as described in the section on Text (above). TROUBLE SHOOTING Problem: I am not American, and when I print, Multiplot tries to write on a page that is wider than the paper I use. Solution: Neither am I, and it does work! Ensure that the page width in the preferences program is set to "Narrow Tractor" and that you have not altered the PLT: startup flags in the devs:mountlist file to indicate a larger page size. If necessary, the page size can be set in absolute terms in preferences. Problem: Sometimes when I run Multiplot, it doesn't seem to be able to find its palette file or the conversion utilities, even though they are right in its own directory. Solution: Multiplot remembers where these files are by their full path specification. If another disk or device exists with the same name as the disk Multiplot resides on, it may not be able to find the files. The commonest problem results from naming the Multiplot disk "Empty" or a data disk "Multiplot". Problem: When I try to print a plot, PLT can't find the file pltfontnames. Solution: Pltfontnames must reside in a device called PLTDATA:. This is best done by assigning PLTDATA: to the directory in which pltfontnames is kept. Problem: When using print Preview or print, Multiplot just hangs even though there doesn't seem to be anything wrong with the PLT device if a file is sent to it from the CLI. Solution: The PLT device must be run at a higher or equal priority than/as Multiplot. Because the two tasks interact, if Multiplot waits for PLT to finish and PLT is at a lower priority than Multiplot, it too, will wait. This can be corrected by running Multiplot from a CLI at 0 priority, or by setting the priority of the PLT: handler to 5, instead of 0 which the docs suggest. Problem: I set a data set to be shown as a line, and then changed my mind, and reset it as a point plot, but I forgot to change the point size, and the data set has disappeared, and I can't find any of the points to select it again. Solution: Use the Redefine Plot option on the ACTION menu to review all the settings for all data sets. When you get to the "lost" set, select a point size greater than zero. Problem: After setting the number of significant figures, I don't notice any change in the significant figures used in the legends. Solution: The significant figures option is accessed at the time the values are calculated. To change the number of significant figures in values on screen, you will need to force a recalculation by deleting the line fit, and recalculating it. Problem: I use WShell and am having trouble with many of the save menu options in Multiplot. Solution: A bug in WShell assumes that any CLI command in quotes ("") is an ARexx command. This contravenes Commodore guidelines and as yet I have not been able to devise a work around. W Hawes is aware of this problem. Problem: I want to print the postcript output of Multiplot with Post (a postscript printer emulator), but when I try, the text prints as shapes, not characters. Solution: The Postscript output of Multiplot currently uses the post- script font Helvetica for output. If you can, you should place the postscript font Helvetica in you PSFonts: directory. If that is not possible, make a copy of FunkyFonts (available with Post), and rename it Helvetica. Then edit the FunkyFonts file with a text editor, and change every iteration of 'FunkyFonts' to 'Helvetica'. CHANGES SINCE XLNd NOTE: Multiplot is now WB2.0 compatible. Style Change: The CLI arguments now require a '-' before every flag, not just before the group of flags. Note that a space must be left between each flag and the flags and the file name (if any). Style Change: Control is now stolen from the Plot window when a requester opens. Style Change: The Select Data window now closes while the file requester is in use. This avoids visual confusion between the two windows. Style Change: The requesters have been redesigned so as to fit in a NTSC non-interlace window. They fit, but they look pretty weird. The vertical stretch that occurs results in some visual confusion with the orientation gadget on the Print Setup window. Please be careful. Style Change: The OPTIONS/Palette/Save menu selection has been removed and its function is now available under PROJECT/Save defaults. The OPTIONS/Palette/Alter option is now available under OPTIONS/Palette. New Mode: Non interlace screens are now supported, and may be selected by either CLI argument (-i) or by tool type setting of the icon (MODE=HIRES). New Feature: Overlays are now used. The code and data for the requesters are not loaded until they are called. This dramatically reduces memory requirements. Multiplot can now be run on a 256k Amiga. (of course you won't be able to load any data...) New feature: Category axes are now provided to enable rapid visualisation of scattergrams. New feature: Select dragging can be locked into vertical movement only, by holding down the 'v' key. New feature: Select dragging can be locked into horizontal movement only, by holding down the 'h' key. New feature: Multiple graphs can be edited and printed at once. New feature: Files can be added to an existing graph. New feature: Data sets can be added to an existing graph on the fly. New feature: New points can be added to an existing data set on the fly. New feature: Histograms are now supported. Bug fix: An array overrun was identified with "Enforcer" and fixed. Bug fix: A bug in the Lattice function scanf() was identified and a workaround introduced. Bug fix: A major bug in Lattice blink was identified and avoided by linking with the alpha version of Blink 6.03. Bug fix: A failure to return all memory allocated has been fixed. THE FUTURE Probable enhancements to come are: font requester, ARexx support, direct WorkBench printer support and multiple axes. Suggestions welcomed. BETA TESTERS WANTED If you would like to see the latest version of Multiplot, why not volunteer as a beta tester or ask for the latest version? Send a stamped self addressed envelope and disk to the address below. CONCLUSION Multiplot was the first intuitive Data plotting program for the Amiga. It has since been joined by a number of other programs which enable the display of experimental data but is unrivalled for ease of use, stability and flexibility. It allows extremely rapid visualisation of experimental data with a wide selection of output formats. It does a simple job, but does it well. If you have suggestions, questions, bug finds, please write: Dr Alan G Baxter, Immunobiology Laboratory, Massachusetts General Hospital, MGH East, Bldg. 149, 3rd Floor, 13th Street, Charlestown, MA 02129 USA Email: BAXTER@HUSC3.HARVARD.EDU Thanks to: Tim Mooney for the great code. Graeme Riddle and Jens Hohmann for testing. Peter Leviton for help with the maths. Rich Campeaux and Jim Miller for suggestions and the PLT: device. Peter Cherna for fixing the event loop. Peter da Silva for the Standard File Requestor. RJ Mical for the palette requester. Barney Kaufman via Steven Owen for the polynomial fitting.