home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 231.lha / PlotXY / plotxy.doc < prev    next >
Encoding:
Text File  |  1989-04-08  |  13.7 KB  |  301 lines
  1.  
  2.  
  3.                             PlotXY Version 1.0
  4.                                    By
  5.                               Robert Mack
  6.                             Copyright, 1989
  7.  
  8.  
  9.  
  10.  1 Introduction 
  11.    ------------
  12.  
  13.        PlotXY is a 2-D plotting package that plots X and Y data points 
  14.    from a file on several types of graphs.  PlotXY was written completely
  15.    in C using the Manx Aztec V3.6a C compiler.  PlotXY was compiled using
  16.    the +fi option for the IEEE Double Precision Floating Point Emulation
  17.    and linked using the mal32.lib for access to the Amiga's library.
  18.  
  19.        There are several good plotting programs in the public domain,
  20.    but the majority of them accept only a mathematical function as
  21.    input (as far as I know).  I wanted a plotting package that
  22.    accepted X and Y data points as input.  I also wanted it to be very
  23.    flexible as far as the output was concerned.  PlotXY allows the user 
  24.    to define just about every aspect of the plot that I could think of.
  25.    The user can determine the type of graph (i.e. linear, linear-log, 
  26.    log-linear, log-log, and histogram), the size of the graph (by input 
  27.    or interactively), the color of the graph and data, the marker type, 
  28.    the line type (although there are only 6 pre-defined types), annotation
  29.    and title, and the graph characteristics (i.e. X /Y bounds, major/minor
  30.    tick marks, grid, and overlay option).  Also included are linear 
  31.    regression analysis and polynomial fit analysis.  All these options 
  32.    are explained in detail section 3.
  33.  
  34.         PlotXY is in the public domain.  The author grants permission 
  35.    to duplicate this software provided that no commercial gain can be 
  36.    had as a consequence of use or reproduction of this software and 
  37.    that this and other identifying information be left intact.  The author 
  38.    may not be held liable for the consequences of use or misuse of this 
  39.    software.  
  40.  
  41.  2. How to get started using PlotXY
  42.  
  43.        I've provided several example input files so that you may
  44.    experiment PlotXY.  The files are:
  45.  
  46.        lotto.dat   Frequency of the Maryland Lotto numbers
  47.                    picked from the beginning to 01/14/89.
  48.  
  49.        sine.dat    The sine of 0 to 360.
  50.  
  51.        tempf.dat   The temperatures (degrees F)at Baltimore for 
  52.                    72 hours (I don't remember the dates...sometime
  53.                    in the fall).
  54.        
  55.    The following is an example of typical steps that are used 
  56.    to plot a X/Y graph with PlotXY.
  57.  
  58.     1) PLOTXY expects there to be a logical device "GDATA:", which 
  59.        corresponds to the directory where the data for plotting is
  60.        located.  This can be accomplished using the CLI "ASSIGN"
  61.        command (i.e., ASSIGN GDATA: DF1:Graphdata).
  62.  
  63.     2)  Open and read the data file.  Choose the menu item OPEN
  64.         in the project menu.  A file requester is presented for 
  65.         selection.
  66.  
  67.     3)  Choose the graph type under the Graph Type menu.
  68.  
  69.     4)  Next choose the graph options you want under the Utilities
  70.         menu.  The default is a point plot.  You may also choose to
  71.         plot a line connecting the data points.  The point, line, grid,
  72.         and overlay options can all be activated at the same time.
  73.         They are not mutually exclusive.  If they are activated, a
  74.         check mark will appear be for an item.  To turn them off, you
  75.         must reselect the item.  The check mark will no longer be
  76.         displayed.
  77.  
  78.         Setup may be activated to set up the graph characteristics.
  79.         If Setup is not picked at this point, it will be displayed 
  80.         before the graph is plotted.
  81.  
  82.     5)  Choose the graph and background colors from the Color menu.
  83.  
  84.     6)  Plot the graph using the Draw item under the Project menu.
  85.  
  86.  3. Description of Menu Items
  87.  
  88.  3.1 Project Menu
  89.      ------------
  90.      Draw - This menu item initiates the plotting of the graph.  After
  91.             the user acknowledges that he/she wants to begin, a setup
  92.             window appears. This window allows the user to set up 
  93.             different plot characteristics (see Setup menu item under 
  94.             the Utilities menu for details).  Note: This window will not
  95.             appear if the user has already chosen the plot's characteristics
  96.             using the setup menu item under Utilities.
  97.  
  98.      Open - Open a text file containing n points to plot (max 1000).  The
  99.             file must have the following format:
  100.  
  101.             record 1     Number of points (integer)
  102.  
  103.             record 2        X1                Y1
  104.             
  105.             record 3        X2                Y2
  106.  
  107.               .             .                 .
  108.             
  109.               .             .                 .
  110.  
  111.             record i        Xn                Yn
  112.  
  113.             X and Y can be either floating point or integer. If you plan
  114.             on doing a line plot make sure the points are sorted.  PlotXY
  115.             does NOT sort the points.  A file requester will be presented
  116.             for file selection.
  117.  
  118.      New - Erase the screen (plot) for a new plot. The file opened
  119.            previously is still active.
  120.  
  121.      SaveIFF - Save the screen (plot) as an IFF file.  A file requester
  122.                will appear for the user to enter the IFF file name.
  123.  
  124.      Print - Print the screen (plot) to a dot matrix line printer.  There
  125.              is an option to set the background color to white for 
  126.              printing on a black and white dot matrix printer. (I've
  127.              never tried it on a color printer).
  128.  
  129.      Credits - This item displays a window that gives credit for the
  130.                public domain routines that were used.  Thank you. 
  131.  
  132.      Quit - Quit PlotXY.
  133.  
  134.  3.2 Graph Type Menu
  135.      ---------------
  136.      Linear -  Indicates a linear graph is desired (default).
  137.      Linear-Log - Indicates a linear-log graph is desired.
  138.      Log-Linear - Indicates a log-linear graph is desired.
  139.      Log-Log - Indicates a log graph is desired.
  140.      Histogram - Indicates a histogram graph is desired.
  141.  
  142.  3.3 Analysis Menu
  143.      -------------
  144.      Linear Regression - Linear regression allows you to analyze one
  145.                          variable's relationship to another.  The method
  146.                          is to perform a least-squares linear regression
  147.                          which is designed to minimize the sum of the
  148.                          squares of the deviations of the actual data 
  149.                          points from the straight line of best fit.  In
  150.                          practice, a plot of the data points is made
  151.                          and then a line is constructed (by selecting
  152.                          the Linear Regression Item) that uniformly 
  153.                          divides the points.  The data color and line 
  154.                          type is chosen at this point.  The line is 
  155.                          described by y = mx + b, where m is the slope 
  156.                          of the line and b is the intercept.  The 
  157.                          correlation coefficient, which is a measurement 
  158.                          of how well the line fitted to the data actually 
  159.                          does approximate the data, is also calculated.  
  160.                          These parameters are displayed in a separate 
  161.                          window.
  162.  
  163.      Polynomial Fit - Polynomial fit uses a higher order polynomial
  164.                       for a reasonably good representation of a series
  165.                       of n data points (X,Y).  The regression coefficients
  166.                       are also estimated.  The technique employs a
  167.                       least-squares fit of the data by a polynomial of
  168.                       order m, where m = 1,2,...10 (maximum of 10) and
  169.                       examines the standard deviation s about the regression
  170.                       line.  The linear regression of Y upon a single 
  171.                       variable X can be extended to the multiple regression:
  172.                       Y = a + b1X1 + b2x2 + ... + biXi + ... + bkXk,
  173.                       where X1,X2,...,Xk are k different variables.  If, as
  174.                       frequently occurs, X1 = X, X2 = X**2, X3 = X**3, etc.,
  175.                       we have a special case of multiple regression known as
  176.                       polynomial or curvilinear regression.
  177.  
  178.                       After the data points have been plotted, select
  179.                       the Polynomial Fit item under the Analysis menu.  
  180.                       The user is then prompted, via a string gadget, to 
  181.                       enter the order of the polynomial that will be used.
  182.                       The color and line type are also selected.  A curve 
  183.                       is then plotted on the graph.  A separate window is 
  184.                       presented that displays: 1) the polynomial order, 
  185.                       2)the standard deviation, 3) the coefficient a, and 
  186.                       4) each bk regression coefficient.
  187.  3.4 Utilities Menu
  188.      --------------
  189.      Point - Plot a character marker for the data point (default).  
  190.  
  191.      Line - Plot a line connecting the data points.
  192.  
  193.      Grid - Plot a dashed grid at the major tick marks on the 
  194.             background.
  195.  
  196.      Overlay - This option is used to overlay data from a different
  197.                file onto the previous graph.  If this item is picked,
  198.                the previous options remain.  All that is plotted are
  199.                the new data.
  200.                
  201.      Setup - Setup opens a window with gadgets that allow the user
  202.              to change the graph characteristics.  The following is 
  203.              a list of graph characteristics that can be changed:
  204.  
  205.              Graph Bounds (float)
  206.              ------------------
  207.              XMAX - X maximum
  208.              XMIN - X minimum
  209.              YMAX - Y maximum
  210.              YMIN - Y minimum
  211.              
  212.              Initially the graph bounds default to the X and Y data bounds
  213.              (X and Y minimum and maximum).  Log plots default to 
  214.              XMAX and YMAX = 1000.0 and XMIN and YMIN = 1.0.
  215.  
  216.              Tick marks (integer)
  217.              --------------------
  218.              XMAJ - major tick marks along the X axis. Default is 5.
  219.              YMAJ - major tick marks along the Y axis. Default is 5.
  220.              XMINOR - minor tick marks along the X axis. Default is 5.
  221.              YMINOR - minor tick marks along the Y axis. Default is 5.
  222.  
  223.              Box size (float)
  224.              ---------------
  225.              XUL - The pixel upper left hand corner of the graph.
  226.              YUL - The line upper left hand corner of the graph.
  227.              Width - The graph width.
  228.              Height - The graph height.
  229.  
  230.              Features 
  231.              --------
  232.              Marker type - The marker type specifies what character is
  233.                            drawn to mark the data point.  The default is
  234.                            "+".  WARNING: The character font I use is
  235.                            the Siesta.font (Microsmiths).  I adjusted the
  236.                            X and Y for the TEXT command to make the 
  237.                            characters draw so that the data point is
  238.                            at the middle of the character.  I checked the
  239.                            default Topaz font and it looks okay, but other 
  240.                            fonts may not be centered.  If this is a problem,
  241.                            let me know.  I use the Siesta font because it
  242.                            looks the best (IMHO). 
  243.  
  244.              Data color - Change the color for the data.  Default is green.
  245.                           See color menu for default colors.
  246.  
  247.              Precision - Precision is the number of decimal places that 
  248.                          are plotted to the left of the decimal point 
  249.                          (i.e. 0 plots integer).  The default is 1.
  250.  
  251.              Line pattern - Change the line pattern. The line option must
  252.                             be active.  The default is a solid line.
  253.  
  254.      Box Mode - Enables the user to shape and move the graph box
  255.                 interactively via the mouse.  Menu options control 
  256.                 whether the box is being sized (shaped) or moved.  
  257.                 Use the left mouse button to define the box. Initially 
  258.                 this option is set to shape the box.  Exit when you 
  259.                 are satisfied with the size and location.
  260.                 
  261.  
  262.      Filter - This option does a running mean on the Y data to 
  263.               perform a smoothing.  Enter the number of Y data points
  264.               to use in the running mean.  The data points must be sorted.
  265.  
  266.      Annotate - This option allows the user to write text for the plot.
  267.                 A string gadget is presented for input of a character
  268.                 string of up to a maximum of 132 characters.  Move the 
  269.                 text with the mouse to the location desired.  Define 
  270.                 the location by pressing the left mouse button.
  271.  
  272.      Title - This option lets the user write a title in the window's
  273.              title bar.  The string may be up to a maximum of 132 
  274.              characters. 
  275.  
  276.  3.5 Colors - default colors: black, blue, green, cyan, red, magenta, 
  277.      ------   yellow, and white.
  278.  
  279.      Background - Set the background color by selecting the appropriate
  280.                   box (default: black).
  281.  
  282.      Foreground - Set the graph color by selecting the box (default: blue).
  283.  
  284.      Palette - Make your own palette by using C. Heath's public domain
  285.                palette tool.
  286.  
  287.  4.0 Remarks
  288.      -------
  289.  
  290.        PlotXY is my first program that I have released as public domain.
  291.     I've learned how to program in C on my Amiga writing PlotXY and other
  292.     programs.  Therefore, I am very interested in any comments, suggestions,
  293.     and complaints that you may have.  Please let me here from you.  I can
  294.     be reached on BIX as RMACK or PLINK as OTR763. You can also write
  295.     me:
  296.  
  297.               Bob Mack
  298.               13909 Briarwod Drive Apt. 312
  299.               Laurel, Maryland 20708
  300.  
  301.