home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 449b.lha / Multiplot_XLNb / Docs / multiplot.doc.pp / multiplot.doc
Text File  |  1990-12-08  |  46KB  |  933 lines
  1.  
  2.                                    MULTIPLOT XLNc
  3.  
  4.  
  5.                These programs are available for free* distribution.
  6.             All rights to the source code, programs and text belong to,
  7.               and copyrights are held by, Alan Baxter and Tim Mooney.
  8.  
  9.        DISTRIBUTION CONDITIONS SPECIFICLY EXCLUDE REDISTRIBUTION FOR PROFIT.
  10.  
  11.                                     July 1990
  12.                           Walter & Eliza Hall Institute,
  13.                          c/o PostOffice, Royal Melbourne
  14.                         Hospital, Parkville 3053. VICTORIA
  15.  
  16.  
  17.      This is the third version of Multiplot XLN. It is expected to receive
  18.      world distribution via the Fish Freely Distribuatable Software Collection.
  19.      If  you   notice  any repeatable bugs  or have  any suggestions  for
  20.      improvement of enhancement, please send them to me at the address below.
  21.  
  22.      CHANGES SINCE JUNE 1990 BETA
  23.  
  24.      Bug fix: New legends no longer overwrite each other.
  25.  
  26.      Bug fix: All requesters can be removed by hitting the return or escape keys.
  27.  
  28.      Bug fix: Point plots with a point size of zero no longer invoke the master.
  29.  
  30.      Bug fix: Deleting a legend by double clicking on it and manually erasing
  31.               text no longer summons the great one.
  32.  
  33.      Bug fix: Step plots now work properly with data sets larger than 31 pairs.
  34.  
  35.      Bug fix: The Logarithmic fit has been renamed Exponential fit.
  36.  
  37.      Bug fix: The legend for an exponential fit had the logarithm of the prefactor.
  38.  
  39.      New feature: The Data Selection Window now has a button to clear the data file
  40.               name if the program is to be invoked without data. It is now possible
  41.               to transfer data to Multiplot entirely via the clipboard.
  42.  
  43.  
  44.      CHANGES SINCE LAST VERSION
  45.  
  46.      Bug fix: The Cross Hair used to appear at the top left of the screen after
  47.           redrawing the plot or zooming.
  48.  
  49.      Bug fix: The colour of the grid or tic marks was reset to light blue after
  50.           redrawing the plot or zooming.
  51.  
  52.      Bug fix: The screen opening routines have been corrected to cope with those
  53.           terrible scrolling workbenches some people like.
  54.  
  55.      Bug fix: The pointer did not change to the Zzz balloon when printing.
  56.  
  57.      Bug fix: Text size handling has been fixed. Code has been added in
  58.           in preparation for the AmigaOS 2.0 font selecter gadget.
  59.  
  60.      Bug fix: The ability to handle large values has been improved. Now limited
  61.           only by the address size of a double (I hope) ie: +/-10e-307 to
  62.           +/-10e+307. Data files and clips may contain values in scientific
  63.           notation.
  64.  
  65.      New feature: Multiplot can open a screen of 2,4,8 or 16 colours depending
  66.           on available memory and user requirements. The number of colours
  67.           available may be set by changing the BITPLANES value in info on the
  68.           workbench, or by including the -b# option from the command line.
  69.  
  70.      New feature: Multiplot can now run on a 1/2 Mb machine.
  71.  
  72.      New feature: Clipping at axis boundaries has been added.
  73.  
  74.      New feature: The ability to save a plot has been added. The file format
  75.           is flat ascii similar to the input file, with extra information
  76.           stored in lines starting with the reserved keyword *AUTOSCRIPT*.
  77.           (*AUTOSCRIPT* is a trademark of BioSoft Pty Ltd.)
  78.  
  79.      New feature: Support for line types has been added.
  80.  
  81.      New feature: The ability to delete a data set has been added. This is
  82.           achieved by pushing the kill button on the CUSTOM PLOT window
  83.           which may be called by double clicking on any point in the data set
  84.           to be deleted, selecting the plot and then choosing the Delete
  85.           option from the EDIT menu, or selecting the plot and then pressing
  86.           the DELETE key on the keyboard.
  87.  
  88.      New feature: The ability to undelete deleted text or data sets has been
  89.           added.
  90.  
  91.      New feature: Clipboard support has been added. Data sets and text may be
  92.           cut and pasted between plots; data can be imported and exported via
  93.           the clipboard.
  94.  
  95.      New feature: The maximum limit of 255 points per data set has been lifted.
  96.           As far as I know, the number of data points per data set is limited by
  97.           memory alone.
  98.  
  99.      New feature: Axis labels and a title can be edited or created from within
  100.           the program.
  101.  
  102.      New feature: A legend may be created for the plot by adding the line
  103.           "*LEGEND* DataSetName" to the top of the data for each data set.
  104.           The legend will appear in the right margin, but may be dragged
  105.           to any other location. The right margin may be eliminated by
  106.           selecting the RightMargin option from the OPTIONS menu. Legends
  107.           may be created from within the program by selecting a data set and
  108.           choosing Add Text from the EDIT menu.
  109.  
  110.      New feature: Legend text may be edited by double clicking on it, moved
  111.           by click/dragging and deleted by selecting it and either choosing
  112.           the Delete option from the EDIT menu, or pressing the DELETE key
  113.           on the keyboard.
  114.  
  115.      New feature: Minimum and maximum X and Y axis values can be requested.
  116.           Plotting code is completely reversible and if the minimum and maximum
  117.           axis values are reversed the plot will be redrawn upsidedown and
  118.           back to front.
  119.  
  120.      New feature: The type of axes  can be  selected from the OPTIONS menu
  121.           on the PLOT window.
  122.  
  123.      New feature: New plot type: Step graphs. Step graphs are useful for
  124.           displaying survival curves and other sorts of data that are obtained
  125.           after descrete time intervals.
  126.  
  127.      New feature: The PLOT window now has a menu option to remove both X and Y
  128.           axis locks.
  129.  
  130.      New feature: It is now possible to toggle the error bars on and off from
  131.           within the PLOT window.
  132.  
  133.      New feature: The Delete and Escape keys on the keyboard are now supported.
  134.  
  135.      New feature: Line fitting has been added. Currently linear and exponential
  136.           fits are supported. The line fit is created as a new data set with its
  137.           formula in the legend.
  138.  
  139.      New feature: Data smoothing has been added. The smoothed line is created as
  140.           a new data set.
  141.  
  142.      New feature: Abitrary text placement has been added. Text may be edited by
  143.           double clicking on it, moved by select/dragging, and deleted by
  144.           selecting it and either choosing the Delete option from the EDIT menu
  145.           or pressing the DELETE button on the keyboard.
  146.  
  147.      Style change: All boxes requesting numerical input now have flanking arrows
  148.           to enable response with the mouse.
  149.  
  150.      Style change: The "Define Plot" window has been removed. Instead a default
  151.           plot  is  drawn  which  can  be  edited by selecting the object to be
  152.           altered by double clicking the  mouse.  This  now  conforms  with the
  153.           "select-action" standard of interfaces.
  154.  
  155.      Style change: Plots or data sets may be group selected by clicking on one,
  156.           and holding down the shift key while clicking on other items to be
  157.           group selected. Note only data sets OR text blocks may be selected
  158.           together.
  159.  
  160.      Style change: The arrangement  of the  menu items  on the PLOT window has
  161.           been altered to provide a better clustering of actions. The Edit
  162.           menu has been renamed ACTIONS and the Commodore standard  Edit menu
  163.           has been added providing clipboard support.
  164.  
  165.      Style change: The imagery for the STOP button has been altered to conform
  166.           to the internationally accepted symbol.
  167.  
  168.      Other changes: Plot2Draw has been altered to handle line types, and has
  169.           been recoded to compensate for a bug in Pagestream which prevented
  170.           direct importation into Pagestream sometimes.
  171.  
  172.      Other changes: The HPGL output has been altered so that connecting lines
  173.           are drawn continually. This saves on plotter pens, and speeds the
  174.           PLT: output considerably.
  175.  
  176.      Other changes: Memory usage has been improved and memory is now alocated
  177.           in a more conservative manner.
  178.  
  179.  
  180.      HISTORY
  181.  
  182.      Multiplot was originally written by Tim Mooney as  a plotting  utility for
  183.      use with  mCAD, his  freeware CAD  program. It  supported a flexible input
  184.      textfile format, many plotting  options, and  HPGL plotter  output. It was
  185.      not an  intuitive program, and its full power was difficult to realize. It
  186.      was also very limited in output formats and had no support for printers.
  187.      Some of these problems were  addressed  in  PLOT,  an  intuition interface
  188.      which  created  an  environment  from  which Multiplot and a collection on
  189.      conversion  files  could  be  called.  However  the  major  problem  of  a
  190.      non-intuitive  way  of  selecting  plotting  options remained (the "How to
  191.      Plot" window), and it  was not  possible to  print output  from within the
  192.      program.
  193.  
  194.      Multiplot XLN resolves these problems.
  195.  
  196.  
  197.      DISTRIBUTION CONDITIONS
  198.  
  199.      Multiplot is not in the public domain. It is neither freeware, shareware
  200.      nor commercial. It may be freely distributed, but not included in a
  201.      commercial package, compilation collection, or sold, traded, leased or
  202.      hired in any form or on any media without express consent of both
  203.      authors. It is periodically released to Mr Fred Fish, who is licensed to
  204.      distribute it in any form he sees fit providing the distribution package
  205.      contains documentation, source and examples. This package may then be
  206.      compressed and posted on any non-profit electronic distribution service.
  207.      Specifically, inclusion of Multiplot on commercial electronic information
  208.      services or in software compilation collections which are sold for profit
  209.      is forbidden and breeches will be pursued with a tenacity rarely seen.
  210.  
  211.      All rights to the source code and programs are reserved. Modifications may
  212.      be made to the source code for personal use to suit local requirements,
  213.      but should not be widely distributed. We would very much like to see such
  214.      modifications to consider inclusion in the generally distributed version.
  215.  
  216.      The inclusion of the PLT: device with Multiplot in no way implies any
  217.      change in, or affects the distribution conditions of that package. Please
  218.      read the documentation provided with PLT: for further information.
  219.  
  220.  
  221.      SUMMARY
  222.  
  223.      Multiplot XLN  is a  fully intuitive  data plotting program. It plots data
  224.      points as (x,y) coordinates  with  or  without  error  bars.  It  can plot
  225.      an unlimited number of sets of any number of data points  using colour,
  226.      line type, point shape and point size to represent the diferent sets.
  227.      A set may be joined by  a line or plotted as discrete points. Data may be
  228.      scatter plotted, or shown as a step graph. The input file for multiplot is
  229.      a simple textfile and my be created in the NotePad or saved from any
  230.      spreadsheet.
  231.  
  232.      Output may be in any of the following formats: IntroCAD, Draw, mCAD, IFF,
  233.      HPGL. The graph can be printed to any workbench printer by transparent use
  234.      of the PLT: device.
  235.  
  236.  
  237.      REQUIREMENTS
  238.  
  239.      Workbench 1.3 (or higher) containing:
  240.           Maths libraries
  241.           The C: directory must contain the files c:run, c:failat and c:mount.
  242.  
  243.      The PLT: device consisting of:
  244.           Plt-handler in the l: directory
  245.           The mountlist entry for plt added to the devs:mountlist
  246.           Assignment of the PLTDATA: directory containing PLT fonts.
  247.  
  248.      At least 1/2 Mb RAM.
  249.  
  250.      The files Multiplot, txt_2_icad and plot2draw must be kept together in the
  251.      same directory.
  252.  
  253.      Text on  screen currently  uses Courier font sizes 14 and 24 point. If
  254.      these fonts are absent, the default font will be used.
  255.  
  256.  
  257.      INPUT FILE FORMAT
  258.  
  259.      Multiplot accepts a simple ASCII file for input of data. This file  may be
  260.      written on  any simple  editor, including the NotePad, or may be generated
  261.      as a  textfile  from  a  spreadsheet.  Multiplot  does  not  choke  on the
  262.      linefeed/carriage-return of  IBM style spreadsheets. The data must consist
  263.      of columns  of numbers and need not contain text.
  264.  
  265.      Text heading  the file  will be  ignored and may be used for an
  266.      explanatory note. Lines beginning with the text below are of special
  267.      significance:
  268.  
  269.      *TITLE* Text will be used for a title (optional).
  270.      *XLABEL* Text will be used for a label on X axis (optional).
  271.      *YLABEL* Text will be used for a label on Y axis (optional).
  272.      *LEGEND* The text will be used as a label for the following data set
  273.               (optional).
  274.      *SCALFACT*  The  numbers  following  will  be  multiplied  to  data in the
  275.      respective columns (optional).
  276.  
  277.      *AUTOSCRIPT* is a reserved keyword that indicates the file has been written
  278.      by Multiplot. It should not be used in import files. (*AUTOSCRIPT* is a
  279.      trademark of BioSoft Pty Ltd.)
  280.  
  281.      *EXTRATEXT* is a reserved keyword that indicates that arbitrary text and
  282.      its placement has been written by Multiplot. It should not be used in
  283.      import files.
  284.  
  285.      Note that *LEGEND* and *SCALEFACT* can be used repeatedly through the data
  286.      file.
  287.  
  288.      Blank lines or lines of  text  interrupting  the  columns  of  numbers are
  289.      interpreted  as  separating  sets  of  data,  and each set will be plotted
  290.      individually in, for example, a different colour or point size.
  291.      See "plotme.dat" or "eric.dat" for examples of input file format.
  292.  
  293.  
  294.      STARTING OUT
  295.  
  296.      From the CLI:
  297.  
  298.      multiplot [-[O][B#]] [filename]
  299.  
  300.      Type 'multiplot' with or without the filename of the input data file. If a
  301.      '?' is  used as  an argument,  a simple description of usage is given. The
  302.      '-O' option will prevent an overscan screen being opened. This option will
  303.      have no effect if you are not using an overdimensional workbench. The B
  304.      option will set the number of bitplanes for the screen. The # value must
  305.      immediately follow the B and may be one of 1->4. The number of bitplanes
  306.      affects the number of on-screen colours as follows:
  307.  
  308.      1 bitplane  --->  2  colours
  309.      2 bitplanes --->  4  colours
  310.      3 bitplanes --->  8  colours
  311.      4 bitplanes --->  16 colours
  312.  
  313.      For example, the following are valid invocations of Multiplot:
  314.  
  315.      Multiplot -OB1 plotme.dat  (Autoloads named file into a 2 colour screen
  316.                                   with no overscan)
  317.      Multiplot -B2 plotme.dat   (Autoloads named file into a 4 colour screen
  318.                                   with overscan if Workbench is overscanned )
  319.      Multiplot -B3O plotme.dat  (Autoloads named file into a 8 colour screen
  320.                                   with no overscan)
  321.      Multiplot -B4              (Starts Multiplot with file requester and  a
  322.                                   16 colour screen with overscan if Workbench
  323.                                   is overscanned)
  324.      Multiplot                  (Starts Multiplot with file requester and  a
  325.                                   16 colour screen with overscan if Workbench
  326.                                   is overscanned)
  327.  
  328.      Multiplot maust be started either from within its own directory, or by
  329.      including the file path from the current directory. It cannot be invoked
  330.      by adding it to a default command path like the C: directory. This
  331.      limitation may be overcome by the use of the alias command.
  332.  
  333.      eg:
  334.  
  335.      alias Multiplot "dh0:<path>/Multiplot -O"
  336.  
  337.  
  338.      From the  Workbench:
  339.  
  340.      Double click on the Multiplot icon OR Edit your input file in a simple
  341.      editor (NotePad will do fine), and save with an icon. You can then change
  342.      the file's default tool (INFO from the left hand Workbench menu) to
  343.      Multiplot:Multiplot or whatever the file path  is. Multiplot will then  be
  344.      automatically  invoked  when  the  file  is  double  clicked.
  345.      An alternative to this is to not change the file's default tool, but to
  346.      click on the file to highlight it hold the shift key down, and then double
  347.      click on the Multiplot icon.
  348.  
  349.  
  350.      OVERSCAN SCREENS
  351.  
  352.      If  you  are  using  an  overscan  work  bench (via MoreRows or some other
  353.      trickery) Multiplot will attempt to open  a screen  the same  size as your
  354.      workbench screen.  This enables  you to make the most of the resolution of
  355.      you monitor. It is not usually possible to open a 16 colour interlace high
  356.      resolution screen with overscan unless you have 1Mb chip ram.
  357.  
  358.      The maximum overscan available is 705 x 562 on a PAL machine or 705 x
  359.      450 on an NTSC machine. If the WorkBench overscan exceeds these values
  360.      a default size screen is opened. It is important to note that on PAL
  361.      machines, some saved preferences result in a screen that requires too much
  362.      bandwidth to be supported by a standard Amiga. In this event a shorter
  363.      NTSC sized screen is opened by Amiga DOS, but Multiplot will continue to
  364.      access the screen in the belief it has a PAL sized screen. Providing the
  365.      dimensions of the workbench screen are less that those above and the
  366.      machine has 1 meg chip ram, this may be corrected by quitting the program,
  367.      and shifting the screen to the left in the screen location setter in the
  368.      preferences program.
  369.  
  370.      The default to overscan can be prevented in three ways:
  371.      1) Use a standard Workbench.
  372.      2) If starting from the CLI, use the -O option as the first argument.
  373.      3) If  starting from  the workbench,  set the TOOLTYPES string in the info
  374.      requester for the Multiplot icon to "OVERSCAN=OFF" (without the quotes).
  375.  
  376.      If the system has little chip ram or it is greatly fragmented, Multiplot
  377.      may be unable to open a screen at all. In this case, you will see an
  378.      "Insufficient Memory" warning and the program will quit. Close extra
  379.      windows, quit unneeded programs, and try again. If chip ram is badly
  380.      fragmented, you will need to reboot.
  381.  
  382.      MEMORY CONSERVATION
  383.  
  384.      Multiplot can be used successfully on Amigas with 1/2 Mb RAM or 1/2 Mb
  385.      chip ram, if care is taken to conserve memory. The following measures
  386.      should be used either separately or together, depending on requirements:
  387.  
  388.      1) Assign T: to a disk, not RAM. Multiplot uses the T: directory to write
  389.         temporary files.
  390.      2) Assign CLIPS: to a disk, not RAM. Multiplot uses the CLIPS: directory
  391.         to store data pasted to the clipboard.
  392.      3) Do not have the fonts Courier.14 and Courier.24 in the FONTS:
  393.         directory. If they are absent, Multiplot will use the default Topaz.9
  394.         font.
  395.      4) If starting from the CLI, use the -O option as the first argument.
  396.         This will prevent Multiplot opening an overscanned screen.
  397.      5) If  starting from  the workbench,  set the TOOLTYPES string in the info
  398.         requester for the Multiplot icon to "OVERSCAN=OFF" (without the quotes).
  399.         This will prevent Multiplot opening an overscanned screen.
  400.      6) If starting from the CLI, use the -B option to reduce the number of
  401.         bitplanes used for Multiplot's screen. This is important for machines
  402.         with 1/2 Mb Chip RAM.
  403.      7) If  starting from  the workbench,  set the TOOLTYPES string in the info
  404.         requester for the Multiplot icon to "BITPLANES=#" (without the quotes).
  405.         If # is less than 4, Multiplot will open a screen with fewer colours.
  406.         This is important for machines with 1/2 Mb Chip RAM.
  407.  
  408.      If Multiplot is run on a PAL Amiga with no overscan and a 1 bitplane
  409.      (2 colour) screen, it uses 208 Kbytes before loading data, and 216 Kbytes
  410.      after loading a moderately large data file.
  411.  
  412.      PHILOSOPHY OF THE USER INTERFACE
  413.  
  414.      Multiplot fully supports the Amiga's graphical user interface. Below are
  415.      listed a few of the important features of this interface that relate to
  416.      the use of Multiplot.
  417.  
  418.      1) An item is a pictorial representation of something on the screen.
  419.  
  420.      2) An item may be selected by moving the mouse pointer over it and
  421.         clicking the left mouse button. This action will highlight, change
  422.         or place a box around the item to indicate that it has been selected.
  423.         If the item is a button ("gadget"), selecting it may invoke some
  424.         specific action. If this is the case, the picture on the item should
  425.         give some idea of what the action is. Multiplot makes extensive use
  426.         of buttons that indicate the status of a selection. For example, the
  427.         line type bauuton has as its picture the type of line currently in use.
  428.         Selecting this button will change the picture and the line type to
  429.         another choice.
  430.  
  431.         Note that the points of a data set are items, but the joining lines are
  432.         not; thus a data set can only be selected by clicking on one of its
  433.         points.
  434.  
  435.         Multiple items can be selected together by selecting one, pressing and
  436.         holding down the shift key, and selecting the rest. This is called
  437.         "group selection".
  438.  
  439.      3) Special activity relating to an item may be started by placing the
  440.         pointer over it and clicking the left mouse button twice in rapid
  441.         succession ("double clicking"). In Multiplot, this action will
  442.         usually open a special window allowing you to edit characteristics
  443.         of the selected item.
  444.  
  445.      4) Some items are movable. An item my be moved by placing the pointer
  446.         over it and pressing and holding down the left mouse button while
  447.         moving the pointer to the new location. This is called select-dragging.
  448.         Only text may be moved in Multiplot. Multiple items can be select-
  449.         dragged by group selecting them first.
  450.  
  451.      5) Some program options are available in menus, which are selected by
  452.         placing the pointer over the title bar at the top of the screen and
  453.         pressing and holding down the right mouse button while moving the
  454.         over the selections that drop down from the title bar. A selection
  455.         is made by releasing the right mouse button over a selection, or
  456.         by clicking the left mouse button. Multiple selections can be made
  457.         by clicking the left mouse button over each of the desired options
  458.         before releasing the right mouse button.
  459.  
  460.      6) The delete key will remove an item that has been selected. The item
  461.         may be retrieved by selecting Undelete from the EDIT menu. Only text
  462.         and data sets may be deleted from Multiplot.
  463.  
  464.      7) The escape key will quit the program, or if a special window is open,
  465.         will quit the window without changes.
  466.  
  467.      8) The return key will allow continuation of work, will proceed to the
  468.         next selection, or will accept changes and implement them.
  469.  
  470.  
  471.      THE DATA SELECTION WINDOW
  472.  
  473.      After being started, Multiplot tries to work out whether it is on a PAL or
  474.      NTSC machine,  and opens  a screen of the appropriate size. If an overscan
  475.      workbench is used, a screen as  large as  possible up  to the  size of the
  476.      workbench screen  will be  opened. The  screen's palette  is read from the
  477.      file "MPlot.def" which should be in either the same directory as Multiplot
  478.      or the s: directory. If it is not found, you will be informed and a screen
  479.      the colour of vomit will be opened. This  should encourage  you to  save a
  480.      new default palette!
  481.  
  482.      The  next thing you may see is  the  DATA SELECTION WINDOW. If you started
  483.      Multiplot by telling it what file you wanted to plot, the file's name will
  484.      be in  a little  box. If Multiplot is invoked without telling it what file
  485.      you want, the default file name will appear  in the  box. The  PATH button
  486.      will  call  up  a  file  requester  to  help with browsing directory trees
  487.      looking for wanted data files. Beneath  the file  selection box  are three
  488.      other boxes  to indicate  what column  the X, Y and Error values are in. A
  489.      '0' indicates values are absent.
  490.  
  491.      For example if the Error box has a '0', no error bars will be  plotted. If
  492.      the X  box has  a '0',  the X  values will  be assumed  to start  at 0 and
  493.      increase by 1 with each data  point.  When  satisfied  with  the  file and
  494.      column specification, hit the return key or click on the Continue=> arrow.
  495.  
  496.      The selected  data file  will be  checked to  ensure it  has the number of
  497.      columns required, and loaded if suitable.
  498.  
  499.      If the file you indentified when invoking Multiplot has previously been
  500.      written by Multiplot, it will autoload without presenting you with the
  501.      DATA SELECTION WINDOW.
  502.  
  503.      If no data file exists, Multiplot may be opened without any data by
  504.      deleting the file name (click on the "None" button, highlight the file
  505.      name entry box and hit Right-Amiga-X, or backspace over the text) and
  506.      hitting return or clicking on the Continue=> button.
  507.  
  508.  
  509.      THE PLOT WINDOW
  510.  
  511.      The PLOT window fills  the entire  high resolution  screen and  contains a
  512.      hand crafted  menu for your computing pleasure. Visible on the window will
  513.      be a default plot of your data. This plot will show lines  and points with
  514.      a different colour and point type for each data set.
  515.  
  516.      The PLOT window contains 5 regions. The central area is where the data is
  517.      represented. The left margin contains the Y values and Y axis label. The
  518.      right margin contains the legend. The lower margin contains the X values
  519.      and the X axis label and the top margin contains the title.
  520.  
  521.      On starting Multiplot, the pointer action is set to SELECT. In this mode
  522.      it is possible to select objects to alter their characteristics. A data set
  523.      may be selected by clicking the left mouse button near one of its points.
  524.      A legend may be selected by clicking the left mouse button on it. In this
  525.      mode, double clicking on an object will call up window to change some
  526.      feature of the object. Double clicking on a point in a data set will call
  527.      up the CUSTOM PLOT window, and allow you to change line type, colour, point
  528.      type and point size of the data set. It will even allow you to skip rend-
  529.      ering that set or delete it completely. Double clicking on a legend will
  530.      call the EDIT TEXT window, to allow you to edit the text in the legend.
  531.      Double clicking in the top margin will call up the EDIT TEXT window to
  532.      allow you to edit or add a title. Double clicking in the bottom or left
  533.      margin calls up the X AXIS or Y AXIS windows, which allow you to set the
  534.      minimum and maximum tic values, the number of tics, and edit the axis
  535.      label. In the SELECT mode, it is also possible to move text around the
  536.      screen by pressing the left mouse button while the pointer is over the
  537.      text, holding it down, and dragging the text to the desired location.
  538.      If the movement is small, a screen refresh may need to by forced by
  539.      selecting the menu option ACTIONS/Redraw.
  540.  
  541.      Several blocks of text can be moved together, without changing their
  542.      relationship to each other by group selecting them. Click on one block
  543.      of text, hold down the shift key and select the others, then without
  544.      releasing the left mouse button, drag the blocks of text to their new
  545.      location.
  546.  
  547.      The pointer action can be set to ZOOM or SLIDE by selecting these subitems
  548.      from the Pointer Action option in the EDIT menu. The action of the pointer
  549.      in these modes is described below.
  550.  
  551.      The menus available are PROJECT which relates to  the loading,  saving and
  552.      printing or plots, EDIT which allows you to delete, copy, paste, import and
  553.      export data and text, ACTIONS which allows modification of the plot,
  554.      resizing, shifting and zoom, OPTIONS which changes the  screen palette,
  555.      changes the axes, grid and cross hair on or off, and FUNCTIONS which allows
  556.      special actions like data smoothing, line fitting and data sorting. The
  557.      major menu selections are described below.
  558.  
  559.      TEXT IN MULTIPLOT
  560.  
  561.      Multiplot supports three kinds of text: Operator independent, operator
  562.      semidependent and operator dependent.
  563.  
  564.      Operator Independent Text
  565.      The title, X axis label and Y axis label are operator independent. Their
  566.      text is rendered in a preset position and cannot be moved. Their content
  567.      can be edited.
  568.  
  569.      Operator Semi-Dependent Text
  570.      The legends are operator semi-dependent. They are created with a small line
  571.      in the relevant colour/line-type to their left and they are placed in the
  572.      right margin which is sized to fit them in an aesthetically pleasing
  573.      manner. They may, however, be moved and the right margin eliminated. They
  574.      may be edited.
  575.  
  576.      Operator Dependent Text
  577.      The text added to enhance a plot (arbitrary text) must be dragged to the
  578.      desired location by the user.
  579.  
  580.      On screen text in Multiplot represents the actual location and size of
  581.      printed text as a proportion of the graph's overall dimensions. The
  582.      printed font used is the HP-GL default font, which is similar to Courier.
  583.      On screen, this font may be represented by any mono-spaced font, and
  584.      Courier is used if present in the Fonts: directory. Otherwise the
  585.      default topaz.9 is used. A font requester will be added in the forthcoming
  586.      OS/2 version of Multiplot.
  587.  
  588.  
  589.      THE PROJECT MENU
  590.  
  591.      OPEN      (Left-Amiga O)
  592.      Returns you to the DATA SELECTION window for loading a new file.
  593.  
  594.      SAVE      (Left-Amiga S)
  595.      Plots  may  be  saved  in  any  of  the following formats: IFF (loads into
  596.      DPaint), Draw  (loads  into  Draw2000  etc),  IntroCAD  (an  excellent CAD
  597.      program), mCAD  (a PD CAD program), and HPGL plotter language. Please note
  598.      the following restrictions: Currently  Draw, IntroCAD,  and mCAD  saves do
  599.      not include the numbers or labels on axes. This is because of the lack of
  600.      font support in these programs. Draw saves require the program Plot2Draw to
  601.      be in  the same directory as Multiplot. IntroCAD saves require the program
  602.      Txt_2_Icad to be in the same directory as Multiplot.
  603.  
  604.      Please Note:
  605.  
  606.      #    Neither Professional Page nor PageStream handle Draw files with large
  607.           dimensions very  well. If your dimensions are greater than 200 units,
  608.           these programs  often scramble  the data.  Rescale your  data to keep
  609.           within  these  limits  if  you  wish  to  import  to  either of these
  610.           programs. Data  may be  rescaled by  adding a  line to  the data file
  611.           which begins  with "*SCALFACT*"  and contains  scale factors by which
  612.           data following is to be multiplied. Scale factor columns map  to data
  613.           columns after the keyword "*SCALFACT*" is discarded.
  614.  
  615.      #    Professional page does not recognise Draw format line types. All line
  616.           type information is lost in transfering Draw format plots to
  617.           Professional Page.
  618.  
  619.      #    mCAD does  not handle  plots with small dimensions very well. If your
  620.           data is in hundredths of units,  mCAD will  not plot  anything on the
  621.           screen. This can be corrected by using *SCALFACT* to rescale data.
  622.  
  623.      #    CAD file  formats are  very poorly  optimised. As  a result, saves of
  624.           large plots may take a long time.
  625.  
  626.      PRINT     (Left-Amiga P)
  627.      Printing is achieved via the  transparent  use  of  the  PLT:  device. The
  628.      plt-handler must  be in  your l: directory, and the PLT: mountlist must be
  629.      added to your  DEVS:mountlist.  You  do  not  need  to  mount  the device.
  630.      Multiplot will mount PLT: automatically if it is not already mounted.
  631.  
  632.      Notes on use of Plt:
  633.  
  634.      #    Plt: opens  its own  window on  the workbench when it starts up. This
  635.           window relays information  about  how  much  of  the  image  has been
  636.           printed and  the remaining  system memory.  It also provides a "close
  637.           gadget" (The square with a dot in it for closing  windows) which will
  638.           abort  the   print.  Use   the  left-Amiga-M   and  left-Amiga-N  key
  639.           combinations to switch between Multiplot's screen  and the workbench.
  640.           This will be corrected in a future release of Plt:.
  641.  
  642.      #    Multiplot  checks  for  the  presence  of  the  Plt-handler in the L:
  643.           directory before attempting  to  mount  Plt:.  If  this  file  is not
  644.           present, Multiplot  will not  print, even if the Plt: device has been
  645.           mounted by some other mechanism.
  646.  
  647.     #     The Plt: device checks the print resolution requested in preferences.
  648.           If you want the nicest possible quality print-outs from Multiplot,
  649.           set your printer density setting (graphics screen 2) to "9".
  650.  
  651.     QUIT      (Left-Amiga Q)
  652.     Quit exits the program without saving any changes.
  653.  
  654.  
  655.     THE EDIT MENU
  656.  
  657.      UNDELETE  (Left-Amiga Z)
  658.      Replaces the last blocks of text or data sets deleted. Only a single level
  659.      of undelete is maintained, but it may contain multiple items if, for
  660.      example, several data sets were group selected and deleted.
  661.  
  662.      COPY      (Left-Amiga C)
  663.      Places a text version of the setected data sets or text blocks in the clip
  664.      board for transfer to another plot or program.
  665.  
  666.      PASTE     (Left-Amiga V)
  667.      Reads the clipboard. If the clip has been written by Multiplot, it will be
  668.      added to the current graph. If it consists of 2 columns of numbers, the
  669.      first column will be assumed to be X values, and the second, Y values. If
  670.      there are 3 columns, the third will be assumed to be error-in-Y. Blank rows
  671.      are interpretted as end/beginnings of data sets. Legends and text can also
  672.      be read, if they conform to the flat file data format described above.
  673.  
  674.      CUT       (Left-Amiga X)
  675.      Places a text version of the setected data sets or text blocks in the clip
  676.      board for transfer to another plot or program, and then deletes it from
  677.      the current plot.
  678.  
  679.      DELETE    (Delete key)
  680.      Removes data set(s) or block(s) of text currently selected.
  681.  
  682.  
  683.      THE ACTIONS MENU
  684.  
  685.      MOUSE ACTION
  686.      Allows the  user to  select the mode in which the mouse works. The options
  687.      are Select, Zoom and Slide.
  688.  
  689.      Select    (Left-Amiga-Shift !)
  690.      The select mode allows the editing of  data  sets  or  axes  by double
  691.      clicking the  left mouse  button over  them. This action calls up a window
  692.      for editing their characteristics. This mode also allows the movement of
  693.      text by click-dragging, and selection of text or data sets for
  694.      manipulation. It is possible to select multiplot data sets my selecting
  695.      one set, and holding down the shift key while selecting the other sets.
  696.      The same method can be used to group select text.
  697.  
  698.      Zoom      (Left-Amiga-Shift #)
  699.      Allows closeup views of areas of the  data,  and  to  adjust  the  axes to
  700.      desired values.  After selecting ZOOM from the menu, the mouse may be used
  701.      to draw a box on the screen  to  indicate  the  area  of  the  plot  to be
  702.      enlarged. This  is achieved by clicking and holding the left mouse button,
  703.      dragging the mouse, and releasing the left mouse button. The maximum limit
  704.      of enlargement  is 1,600 times. Zooming out to reduce the size of the plot
  705.      by one half is achieved by double clicking the left mouse button.
  706.  
  707.      Slide     (Left-Amiga-Shift ^)
  708.      After selection the mouse may be used to  draw a  vector on  the screen to
  709.      indicate  the  direction  and  amount  the  plot  should be moved. This is
  710.      achieved by clicking and  holding  the  left  mouse  button,  dragging the
  711.      mouse, and releasing the left mouse button.
  712.  
  713.      LOCKS
  714.      Allows either  the X or Y dimension to be frozen while the other is zoomed
  715.      or rescaled. very useful when used in conjunction with the  other items in
  716.      this menu (Zoom, Slide, FullPlot). This allows you to arrange the scale of
  717.      the plot to best advantage. The  Subitem X  AXIS will  lock the  amount of
  718.      zoom in  the X  axis, and the subitem name will change to "X LOCK ON". The
  719.      lock may be turned off by  reselecting the  subitem. The  same applies for
  720.      the Y  AXIS selection.  the BOTH  LOCKS ON  selection will lock both axes.
  721.      They can be both turned off with BOTH LOCKS OFF. The amount of zoom can be
  722.      manually set from the X and Y AXIS windows. Unless locked, the following
  723.      options will reset the veiw of your data: Full Plot, Redefine Plot, Sort,
  724.      Linear Fit, Smooth, Exponential Fit.
  725.  
  726.      REDRAW    (Left-Amiga R)
  727.      Redraws the screen with the same zoom as currently set.  It should be used
  728.      to repair the screen of unwanted rendering, or an incomplete refresh.
  729.      This option is different from FULLPLOT  and REDEFINE PLOT which will reset
  730.      to either the full plot, or if the X or Y locks are on, to the locked plot
  731.      size.
  732.  
  733.      FULLPLOT  (Left-Amiga F)
  734.      Redraws the screen with the default axis settings. This plot will show all
  735.      data points and the extremes of any error bars. It will not overcome locked
  736.      axis settings, so if you have defined a set of minimum and maximum axis
  737.      values, it is wise to lock them with the BOTH LOCKS ON option.
  738.  
  739.      REDEFINE PLOT   (Left-Amiga D)
  740.      Presents the user with the  CUSTOM PLOT WINDOW  for  each  data  set in
  741.      succession.  This  is  useful  for  editing  all  data  sets,  editing the
  742.      chacteristics of a data set plotted as a line (when it may be difficult to
  743.      recognise where  the points are for selection with the mouse) or if a data
  744.      set has been skipped  (possible  from  the  Custom  Plot  window)  and not
  745.      plotted. This action is destructive in the sense that any zooming that has
  746.      not been locked will be lost.
  747.  
  748.      ADD TEXT  (Left-Amiga A)
  749.      A legend may be added to an unlabelled data set by selecting it (single
  750.      click of left mouse button near any point of the data set) and choosing
  751.      this menu option. A EDIT TEXT window will appear in which the legend text
  752.      may be typed. This is also another way of editing existing legends, and
  753.      can be used to add arbitrary text if used without selecting a data set.
  754.  
  755.      THE OPTIONS MENU
  756.  
  757.      CROSS HAIR      (Left-Amiga L)
  758.      Provides a cross hair for the cursor to assist with zooming, sliding
  759.      and movement of text blocks.
  760.  
  761.      GRID            (Left-Amiga G)
  762.      Allows the selection of a cross grid, tics, or no marks on the axes.
  763.  
  764.      AXES
  765.      Allows the selection stem and leaf, box or no axes drawn.
  766.  
  767.      RIGHT MARGIN    (Left-Amiga M)
  768.      Toggles the right margin space for legends.
  769.  
  770.      ERROR BARS      (Left-Amiga E)
  771.      Toggles the error bars on and off. This option is ghosted if data for error
  772.      bars is not available.
  773.  
  774.      PALETTE
  775.      The screen palette may be altered by calling the neat requester, which was
  776.      written by  RJ. The  only non  obvious feature of the requester is that by
  777.      clicking the left mouse  button on  the RGB  characters, the  requester is
  778.      converted to a hue/saturation/lightness requester for those who think that
  779.      way. The SAVE Subitem will attempt to write a file called MPlot.def to the
  780.      same directory  as Multiplot,  or failing  that, to the s: directory. This
  781.      file is in the same format  as the  screen palette  files produced  by the
  782.      program "Colour" by a nationalistic Canadian bloke.
  783.  
  784.  
  785.      THE FUNCTIONS MENU
  786.  
  787.      SMOOTH DATA
  788.      Select a data set by clicking the left mouse button near one of its points,
  789.      and then select this menu option. A new data set will be created in which
  790.      each Y value is the mean of the surrounding Y values from the original
  791.      data set. A requester will appear enabling you to enter the number of
  792.      values each side of the point for the mean to be taken over. This action
  793.      is destructive in the sense that any zooming that has not been locked will
  794.      be lost.
  795.  
  796.  
  797.      LINEAR FIT
  798.      Select a data set by clicking the left mouse button near one of its points,
  799.      and then select this menu option. A new data set will be created in which
  800.      will represent a straight line fit of the data. The formula of the line is
  801.      shown in the legend. This action is destructive in the sense that any
  802.      zooming that has not been locked will be lost.
  803.  
  804.      EXPONENTIAL FIT
  805.      Select a data set by clicking the left mouse button near one of its points,
  806.      and then select this menu option. A new data set will be created in which
  807.      will represent a exponential fit of the data. The formula of the line is
  808.      shown in the legend. This action is destructive in the sense that any
  809.      zooming that has not been locked will be lost.
  810.  
  811.  
  812.  
  813.      COMMAND KEY SEQUENCES
  814.  
  815.      Multiplot fully supports keyboard shortcuts using the right Amiga key. A
  816.      full list of shortcuts and mneumonics is listed below:
  817.  
  818.      Key        Command                     Mneumonic
  819.  
  820.      A          ACTIONS/AddText             <A>dd Text
  821.      B          OPTIONS/Axes/Box            <B>ox
  822.      C          EDIT/Copy  (not available)  <C>opy
  823.      D          ACTIONS/ReDefine Plot       Re<D>efine Plot
  824.      E          OPTIONS/Error Bars          <E>rror Bars
  825.      F          ACTIONS/Full Plot           <F>ull Plot
  826.      G          OPTIONS/Grid/Grid           <G>rid
  827.      H          PROJECT/Save as/HPGL        <H>PGL
  828.      I          PROJECT/Save as/ILBM        <I>LBM
  829.      J          not used
  830.      K          PROJECT/Save as/Draw        Save in <K>AD format
  831.      L          OPTIONS/Cross Hair          Cross Hair <L>ines
  832.      M          OPTIONS/Right Margin        <M>argin
  833.      N          PROJECT/Save as/IntroCAD    I<N>troCAD
  834.      O          PROJECT/Open                <O>pen
  835.      P          PROJECT/Print               <P>rint
  836.      Q          PROJECT/Quit                <Q>uit
  837.      R          ACTIONS/Redraw              <R>edraw
  838.      S          PROJECT/Save                <S>ave
  839.      T          OPTIONS/Grid/Tics           <T>ics
  840.      U          OPTIONS/Screen Title        <U>p the top bit of the screen writing
  841.      V          EDIT/Paste  (not available) Commodore guidelines
  842.      W          PROJECT/Save as/Data        <W>rite data
  843.      X          EDIT/Cut    (not available) Commodore guigelines
  844.      Y          OPTIONS/Axes/X and Y        X and <Y>
  845.      Z          EDIT/Undelete               Commodore guidelines
  846.  
  847.      Please note that there are three other keyboard shortcuts that allow you to
  848.      swap between mouse actions. These also require that the right Amiga key is
  849.      held down.
  850.  
  851.      Shift-1    (!)      ACTION/Mouse Action/Select
  852.      Shift-3    (#)      ACTION/Mouse Action/Zoom
  853.      Shift-6    (^)      ACTION/Mouse Action/Slide
  854.  
  855.      The Escape and Delete keys are supported:
  856.  
  857.      Esc        PROJECT/Quit
  858.      Del        EDIT/Delete
  859.  
  860.  
  861.      THE CUSTOM PLOT WINDOW
  862.  
  863.      For each  data set for plotting, this window can be called to allow you to
  864.      select plot colours and whether data  is  plotted  as  a  line,  series of
  865.      points, both, or a step plot. If points are drawn, the point size and point
  866.      type can be selected. If a line is drawn, the line pattern can be selected.
  867.      The colour, plot type (point, line, both),  and  line type  are selected by
  868.      repeatedly clicking  the  left mouse  button on the buttons that represent
  869.      the current selection. The point type is selected from the pannel of six
  870.      mutually exclusive button on the right of the window.
  871.  
  872.      The CONTINUE button will  accept changes  and proceed  to the  Plot window
  873.      where the plot is rendered.
  874.  
  875.      The  SKIP  button  will  skip  a  single  data set, so that it will not be
  876.      plotted when the PLOT window is opened. The missing data set can be
  877.      recalled by selecting the Redefine plot option from the EDIT menu, and
  878.      pushing the CONTINUE button when represented with the data set.
  879.  
  880.      The KILL button is similar to the SKIP button but its effects are
  881.      permanent. A dead data set can be revived with EDIT/Undelete.
  882.  
  883.      The STOP button will skip all remaining data  sets without  presenting the
  884.      Custom Plot  window for  them will  not alter the plotting of the data set
  885.      currently being edited.
  886.  
  887.      THE AXES WINDOW
  888.  
  889.      For either or both the X and Y axes, this  winow can  be called  by double
  890.      clicking the  left mouse  button over the axis to be edited with the Mouse
  891.      Action menu option set to  select.  This  window  allows  the  minimum and
  892.      maximum axis values and the number of tics to be selected, and editing of
  893.      the axis label.
  894.  
  895.      THE FUTURE
  896.  
  897.      Probable  enhancements  to  come  are: font requester, bar graphs, log axes,
  898.      postscript support, splines and polynomial line fitting.
  899.  
  900.      Suggestions welcomed.
  901.  
  902.  
  903.      BETA TESTERS WANTED
  904.  
  905.      If  you  would  like  to  see  the  latest  version  of Multiplot, why not
  906.      volunteer as a beta tester? Send  disk and  return address  to the address
  907.      below.
  908.  
  909.  
  910.      CONCLUSION
  911.  
  912.      Multiplot is  the first  intuitive Data plotting program for the Amiga. It
  913.      allows extremely rapid visualisation  of  experimental  data  with  a wide
  914.      selection of  output formats.  It does  a simple job, but does it well. If
  915.      you have suggestions, questions, bug finds, please write:
  916.  
  917.                                 Dr Alan G Baxter,
  918.                           Walter & Eliza Hall Institute,
  919.                     c/o Post Office, Royal Melbourne Hospital,
  920.                              Parkville 3053, AUSTRALIA
  921.  
  922.                                   WEHI::Baxter_A
  923.                              Baxter_A@wehi.dn.mu.oz.au
  924.                      Baxter_A@wehi.dn.mu.oz.au@MUNNARI.OZ.AU
  925.                         wehi.dn.mu.oz!BAXTER_A@harvard.edu
  926.  
  927.                                 Ph (03) 380 9206
  928.  
  929.      Thanks to Tim Mooney for the great code, Graeme Riddle and Jens Hohmann
  930.      for testing, Peter Leviton for help with the maths and Rich Campeaux
  931.      for suggestions.
  932.  
  933.