WELCOME TO MULTIPLOT/2 v1.2 ---------------------- by Mike Stott NeoDym Systems 15 Nesbitt St Nepean Ontario Canada K2H 8C4 July 1996 QUICK START ----------- Copy the MLTPLT22.ZIP distribution file into a convenient directory on your hard drive. Decompress the MLTPLT22.ZIP distribution file using PKUNZIP (DOS) or UNZIP (OS2). Get an OS/2 command prompt by opening an OS/2 window and change to the directory containing MULTIPLOT2. Now just type: TRYITNOW MULTIPLOT2 should now start and open up a PM window on the desktop and show a plot of the data sets in the sample1.dat file. Read the following documentation and enjoy using MULTIPLOT2. WHAT IS MULTIPLOT/2? -------------------- Multiplot/2 is a versatile, easy to use OS/2 2.X 32 bit Presentation Manager application for manipulation and plotting of technical data sets and generation of publication quality scientific and technical line graphs. On the same chart it can plot many sets of data to the same scale and in a variety of formats,selectable by simple menu 'click'. The data in an individual data set can consist of any number of points (greater than zero) and the points can be at arbitrary, non-uniformly spaced intervals on the x axis.It isn't necessary to tell Multiplot/s how many items are in the data set. It will count them for you. Each line can be automatically plotted in a different colour and line type (i.e. dotted, dashed etc) or fixed as solid and black. The data can be replotted in many different combinations of linear, logarithmic, deciBel or polar by simple menu command. The charts are automatically scaled to accomodate the maximum range of x and y values in the data sets. Scaling is 'sensible' and in a 1-2-5 sequence. If you want to force a larger scale, just include two extra data sets in your data file, each with a single point in it. These points should be the bottom left corner and the top right corner of the chart you want. Axis labels and plot title are entered via the data file containing the numerical data. Annotations can be added via the data file or manually and moved or re-sized in WYSIWYG fashion using the mouse. The plotted chart is displayed in an OS/2 PM window which can be resized or reshaped using the mouse in the normal way. Menu choices are presented in the diplay window to enable the user to direct how the program interpolates between the data points. Available choices (v1.0) are straight line,'low-pass' smoothing, cubic spline and no interpolation i.e. only the points are plotted with no lines in between. The displayed chart can be copied via the clipboard to a suitable PM DTP or word processing program from which the chart can be incorporated into documents and printed. The copying can be made as an os/2 metafile or as a bitmap. Metafile is best as it enables the chart to be resized without loss of quality. Unfortunately os/2 and MS Windows metafiles are different and so this method can only be used with suitably equipped os/2 Presentation Manager programs. The OS/2 'Picture Viewer' is a simple way to display the metafile and print the result on the default printer. It can usually be found at \OS2\APPS\PICVIEW.EXE. Charts copied to the clipboard in bitmap form can be pasted into os/2 PM or MS Windows programs. Note that bitmaps exported from MULTIPLOT/2 are copies of the display window and so reflect any resizing or reshaping made to the window. Metafiles are device independent and so do not resize or reshape with display window changes. Graphs can also be saved to disk files both in metafile or bitmap form. Multiplot/2 has a lot of flexibility in reading and modifying data organised in different ways. For example in 'column' or 'row' format and with one or several 'Y' sequences corresponding to a single 'X' sequence. It can also read data which is expressed in a recycling or modulus fashion, such as day numbers in the week or week numbers in the year. The addition the program can be made to "filter" (i.e. plot or not plot) a point depending on the value of the same or some other point. Using this facility you can selectively plot points which satisfy some separate criteria. You can also add a value to the X and/or Y data so as to offset it and plot it 'modulo' an arbitrary value. The new data thus created can be saved to disk in 'row' or 'column' format, thereby giving you the ability to transpose your data using Multiplot/2. For users who want automated data generation and plotting environments, Multiplot/2 now has an extensive command line control capability. Most features can be controlled from the comand line, including the ability to store the images to disk and to terminate automatically without asking for user input when finished. This is most useful in automated unattended data generation situations where, for example, you want to run a series of programs overnight and look at the graph results next day. HOW TO USE MULTIPLOT/2 ---------------------- SIMPLE OPERATION The easiest way to run the program is to launch from the Work Place Shell. Just display the MULTIPLOT/2 icon (for example by navigating to the directory in which Multiplot/2 is located using the PM 'Drives' object) and double click on it. You can also launch from an OS/2 command line. Navigate to the correct directory using the normal and type MLTIPLT2. A file dialog window will pop up to enable you to select a data file for plotting. Several example data files are included as examples. To make your own data files, arrange your data in an ASCII text file in column format as shown below with the X and Y values on the same line, separated by spaces or tabs. x y x y x y : : : : *** x y x y x y : : : : *** "X-axis label" "Y-axis label" "Plot Title" ### Each group or set of X-Y pairs results in one line on the final plot chart. You can have up to 800 points per line and up to 60 lines on the plot. You don't have to have the same number of points in each line and you don't have to make the points uniforml y spaced along the x axis. If you have a situation where you have several y values all corresponding to the same sequence of x values, you don't have to keep putting in the same x values over again. You can instead put them in like this X y1 y2 Y3 - - X y1 y2 Y3 - - : : : : : : : : *** ::: ### Sometimes you get a situation where your data is arranged in rows rather than in columns. In mathematical terms it is "transposed" -a term borrowed from matrix operations. In this case we get all the X values on one line and all the Y values on the next l ine. We have to tell Multiplot/2 that the data is organized in this way. This is done by putting the keyword xytransposed before the data. For example xytransposed x x x x x y y y y y : : : : : : : : : : *** ::: ### Similarly to the column situation we can have several sets of y's corresponding to the same set of x's. For example xytransposed x x x x Y1 Y1 Y1 Y1 Y2 Y2 Y2 Y2 Y3 Y3 Y3 Y3 : : : : : : : : *** ::: ### You can mix and match these formats in any combination. Just remember to separate each one by the three asterisks separator "***" and to finish off the whole file by a termination string "###". The 3 label/title strings before the final "###" are optional. If you don't put them in, Multiplot/2 will not put any labels or title on the plot. When using a spreadsheet to generate the data, one convenient way to transfer the data to Multiplot/2 is to select columns or rows of data in the spreadsheet and to copy/paste them into an ASCII text editor such as the OS/2 System Editor, E.EXE. You can t hen add the necessary "***" lines and the axis labels, title etc. and save the whole thing as a text file from which you can then plot. Most spreadsheets represent the separator between columns as a tab symbol. So when you paste into E.EXE the columns should be neatly aligned. MENU CHOICES: File: You can choose to exit the program, go back to the file dialog to select another file to be plotted, save the graph image to disk or save the (modified) data to disk in 'row' or 'column' format. Edit: Menu choices copy the displayed chart to the clipboard either as an os/2 metafile or as a bitmap. The size of the bitmap is equal to the size of the displayed chart. Metafiles are device independent and so can be stretched to any size without loss of quality. Edit/Annotate: The Annotate menu choice pops up a 10 Window editing box in which you can generate text strings with which to annotate your chart. (If you include annotation strings in your data file they will be pre-loaded into the editing boxes so you can edit them if you wish). Clicking on 'OK' will put the text onto the chart. New strings go at an arbitrary location and size. To move a text string, just position the pointer over the desired text and press down mouse button 2 (usually the right button). To confirm you have selected the text, it will change colour and the pointer will change to a 'cross' shape. While still holding down button 2, move the mouse to drag the text to where you want. Releasing the mouse button will leave it there. To resize the text, position the pointer over the text then click and release mouse button 1 (usually the left one). The selected text appears with a sizing border containig a black rectangle at the top right hand corner. Place the pointer over this black rectangle and the pointer will change to a cross to indicate that you are properly over it. Then press button 1, hold it down and drag the top right hand corner so that the size and shape of the text is the way you want. Then release the mouse button and the text will fill the re-sized box you just created. Once you have generated some annotation, you can pop up the editing window by double-clicking mouse button 1 on any annotation in the plot window. Interpolation: The menu choices enable the user to determine how multiplot/2 interpolates between the dat points in the dat file. The initial default is straight line linear. One alternative is a 'smoothed' fit with rounding of the sharp corners which would otherwise occur at the data points. The third choice is a cubic spline fit to the data points taken 3 at a time. If the number of points in a set is not a multiple of 3 multiplot/2 ignores the last 1 or 2 points so as to make the number of points plotted a multiple of 3. The fourth choice is no interpolation. Only the data points are plotted using automatic selection of marker shape and color. In a subsection of this menu are some choices which can turn the marker symbols on/off and restore the interpolating line if you have previously turned it off. Line: This sub menu contains a selection of choices for the line colors, line types and line width. They can be used in any combination. The 'auto' modes for color and line type cycle automatically through 14 colours and 6 line type so you should always have a unique combination for each line. Plot: This submenu enables you to redisplay the same data using any combination of linear, logarithmic or dB scales on the X or Y axes. (Note that you cannot plot data containing negative or zero values on logarithmic or dB scales ). MULTIPLOT/2 also has a menu selection to plot all the same data on a polar display. Two forms of polar plot are provided. One assumes angles increase counterclockwise from a horizontal or 'East' axis (mathematical or electrical engineering convention) and the other assumes angles increase in a clockwise direction from vertical or North (navigation or surveying convention). The x values are assumed to be degrees (default) but the number of x units corresponding to 360 degrees on the polar plot can be varied via the 'Modify Data/Axes' Dialog box. Plot/Modify Data/Axes Dialog: This box is activated by a choice in the 'Plot' menu. It enables you to (1)add any amount to the X or Y data prior to plotting. Note that if you add a large amount to, say, y1 you may move the data out of the plotting range currently established by the auto-scaling routine. To bring it back, just rescale the plot by clicking on one of the plot type menu choices, such as 'Y-Linear'. (2) to set the number of X units corresponding to a full circle in the Polar plot (default is 360, so that X would correspond to degrees). If your data X axis was, for example, week number in the year and you set this value to 52 then the same week would fall at the same angle for every year and (3) to control the modulus parameters of the modulus plot capability. This feature changes the labelling of the x or y axis grid lines to be in modulus format. This means that if, again, your data was representing week number then week 60 would be year 1, week 8. Week 110 would be year 2, week 6 etc. The grid labelling automatically changes to show e.g. 2m+ 19. This corresponds to 2 time the modulus plus 19. At the bottom of the dialog window is a set of controls which enable you to override the scaling parameters selcted by the auto-scale feature. INTERMEDIATE OPERATION DATA FORMAT: The data file structure is very straightforward and flexible. It is an ascii text file organised as a series of blocks each containing a sequence of x and y values and finishing with a string of three asterisks *** on a separate line. Each block can be arranged in either column or row format. Column Example: X Ya Yb Yc x1 ya1 yb1 yc1 x2 ya2 yb2 yc2 x3 ya3 yb3 yc3 . . . . . . . . . . . . . . . . xN yaN ybN ycN *** . Block no 2 *** . Block no 3 *** . Final block *** "X Axis Label string" "Y Axis Label string" "Plot title string" "Optional Annotation String #1" "Optional Annotation String #2" . . "Final Optional Annotation String" ### Any text you like can go after the ### sequence. Note that you don't have to tell Multiplot/2 how many points there are. It will count them for you. Just make sure that each row has the same number of items in it. In the above column example, we created 3 data sets (a,b and c) in which each x value in the x sequence has 3 y values associated with it, i.e. we have 3 graph lines. We could have specified each set separately in its own block, but this way is more compact and it corresponds to the way many spreadsheets store their data. Each data set can consist up to 800 graph points.The numerical data can be described in fixed point (e.g. 123.456) or scientific exponential (e.g. 1.23456E2). A minimum of 2 points are required for a straight line or smoothed graph and a minimum of 3 for a cubic spline interpolation. For row format, you have to tell Multiplot/2 that the data is now in a different format. You do this by putting the string xytransposed on the first line. Then you put in the data like this:- Row Example: xytransposed x1 x2 x3.....xN ya1 ya2 ya3....yaN yb1 yb2 yb3....ybN yc1 yc2 yc3....ycN yd1 yd2 yd3....ydN *** . Block no 2 *** . Block no 3 *** . Final block *** "X Axis Label string" "Y Axis Label string" "Plot title string" "Optional Annotation String #1" "Optional Annotation String #2" . . "Final Optional Annotation String" ### Any text you like can go after the ### sequence In the above row example, we created 4 data sets (a,b,c and d) in which each x value in the x sequence has 4 y values associated with it, i.e. we have 4 graph lines each with N points on it. After the row of 3 asterisks following the last of the data sets, the remaining 3 lines define (1) The x axis label (2) The y axis label and (3) the plot title. These lines are ascii strings set within " " marks. If you do not want a label or title, just put in "" . The last line of the file is a string of 3 # signs, ### followed by a 'newline'. This indicates to multiplot/2 that the end of the file has been reached and that it should now plot the data.MULTIPLOT/2 ignores anything after the ### so you can put any notes, comments etc in there. Modulo input: Multiplot/2 has the capability to accept data in which the x values are 'modulo' some number. Suppose we have some data indicating the local temperature as a function of month number in the year and it extends over several years. When we get to December (month 12) the next month 'flips' back to month 1 (January) whereas, obviously, elapsed time kept increasing. If we tell Multiplot/2 that the x data is of this form and what the modulus is, it will sens the 'flip' and keep incrementing the x variable. We do this by putting on either of the first two lines x_is_modulo followed by the modulus. This would be 12 in the last example. The data block might look like this:- x_is_modulo 12 1 -18 2 -15 3 -5 4 5 5 15 6 22 7 28 8 26 9 18 10 10 11 -4 12 -10 1 -16 2 -13 3 -2 4 6 5 16 6 24 7 31 8 23 9 15 10 6 11 -10 12 -15 1 -20 2 -10 3 -8 *** "X= Month Number" "Y= Average Temperature" "Plot of Temperature vs Time" ### If, for instance you wanted to show your heating energy consumption on the same chart, you could either add a second column of y values (assuming that you knew the consumption at the same time values as the temperature) or you could add a second data block plotting the energy consumption for the periods that you did know it, which may not be exact months. That's it! You should now be able to plot the data using Muliplot/2. The sample data files included with the program further illustrate the structure. ADVANCED OPERATION CONTROLLING via THE DATA FILE Multiplot/2 has some more advanced features to control the plotting of the output. These are described below. 1) Axis Mapping This is activated by the keyword axis_map which must appear somewhere within the data block (i.e. between a pair of "***" lines). The syntax is axis_map [x|l|r|n],[x|l|r|l|n],------["Title for right (Y2) axis"] This powerful mapping feature enables you to allocate any row/column number to the X-axis (x), the left Y-axis (l), the right Y-axis (r) or no plot (n). The default is x,l,l,l,--- i.e. the first column (or row if transposed) is allocated to x and all of the y information columns are allocated to the left Y axis. You only need to put in the axis map sequence to the extent that it differs from the default. For example if you wanted t o allocate column 1 to the left Y-axis, column 2 to x, column 3 to the left Y axis, don't plot column 4. Allocate column 5 to the right Y axis and column 6 and up to the left Y axes, then you would put axis_map l,x,l,n,r The label for the right Y axes can be put in " " marks after the axis mapping sequence. The axis mapping mechanism may be used on regular (column) or transposed (row) data. It is effective for all the data in a block between a pair of "***" lines. 2) Filtering Filtering is activated by the keyword filter_on_y somewhere in the data block. The syntax is filter_on_y y-column/row #, low-limit, high-limit The command has the effect of removing from the plot all rows (or columns) for which the specified Y column value does not lie within a range which is set by the low and high limits. For example, suppose we had some measurements of height (x) and weight (y) for a set of cats, dogs, sheep and horses. If we define a species value where cats = 1, dogs = 2, sheep=3, horses =4 and the species value is put in column 2 as shown below Height (x) weight (y) species # 7 10 1 15 35 2 6.5 8 1 24 80 3 60 200 4 65 220 4 30 95 3 20 70 2 filter_on_y 2,0.5,2.5 *** Will cause only the data for cats and dogs to be plotted since only they have a species value which falls between 0.5 and 2.5. If you only wanted to plot cats, you would put filter_on_y 2,0.5,1.5 If you want to exclude data which falls between the low and high limits then you just interchange the low and high values. filter_on_y 2,2.5,0.5 Will plot everything except cats and dogs. Filtering is operative on data in column or row (transposed) form. If you don't want to plot the filtering parameter (the species number in this example) you can delete its line from the plot by use of the axis_map keyword. For example axis_map x,l,n Note that even though the information is not plotted it is still available and can be used for filtering. 3) Right Y axis Multiplot/2 separates out the data between the left and right Y axes and performs separate auto-scale operations for each one. The number of horizontal grid lines is driven by the left Y axis. The right Y axis automatically ensures that the left and right grid lines are coincident. The auto-scaling results can be overridden manually by using the plot/modify data/axes dialogue box. Note that only the start point and increment of the right Y axes can be adjusted since the number of grid lines is set by the left Y axis. COMMAND LINE & UNATTENDED OPERATION To facilitate use in semi-automated environments such as OS/2 command ( .cmd) files the program can be launched from the os/2 command line with the name of the data file to be plotted and a series of optional parameters following the program name. SYNTAX: MLTIPLT2 [source file_name][opcode][options]....[dest'n file] source file_name is a qualified path\name of the file containing the data to be plotted. If datafile_name is in the current directory, just the file name will suffice. If you omit the filename, Multiplot/2 will pop up a file selection dialog window. Key to Multiplot/2 Command Line Syntax mltplt21 srcfile opcode polar_scale x_offset y_offset x_plot_modulus y_plot_modulus destfile ---------|--------|-------|-----------|--------|---------|--------------|--------------|---------- program name of see x units for add to add to plot x modulo plot y modulo name of name source below full circle all x's all y's this value this value dest'n file Opcode is a coded decimal number with up to 6 digits.It controls operation and plot appearance as follows:- '100000' '10000' '1000' '100' '10' '1' Action File Clipboard Interpolation Line Plot D D D D D D 0=Display,wait 0=no save 0=no copy 0=straight 0=all auto 0=linear 1=No Display, 1=save meta 1=copy meta 1=smoothed 1=black 1=polar ccw Terminate on 3=save bmp 3=copy bmp 2=spline 2=thin 2=polar cw completion 3=None- 3=black+thin Points Only 4=solid 5=solid+black 6=solid+thin 7=solid+thin+blk Example #1; opcode 0 (=000000) will display the graph, wait for user instructions and set all display characteristics to their normal default settings. Example #2: opcode 101100 will bypass display, copy a graph metafile to clipboard and then terminate. The graph will be smoothed auto appearance and linear plot. Example #3: opcode 001042 will display the graph, copy a metafile to clipboard automatically, and produce a polar clockwise plot in solid lines with auto color and thick width. Example #4; opcode 110000 will bypass display and save a metafile to disk in the 'destfile' file with no copy to clipboard, straight interpolation auto lines and linear plot etc. CONTACTING NeoDym: ------------------ Via e-mail to neodym@ibm.net or ac902@freenet.carleton.ca Via Fax to 613 596 9015 COPYRIGHT NOTICE ---------------- This application is shareware. It is not free. It is provided to you to enable you to evaluate it for a period of 30 days. If you find it useful you must register as described below. Then you will be licensed to use it but not to resell it, reverse- engineer it or combine it with other software or packaged in a commercial book without permission. If you do not register, then you must stop using it. Copyright remains the property of NeoDym Systems division of 802784 Ontario Ltd. Permission is granted to redistribute the unaltered shareware archive (.zip file) for a small but reasonable copying charge. There is NO warranty. Support is NOT guaranteed to unregistered users. REGISTRATION ------------ Registration costs $20 US or $25 Canadian by check or money order payable to NeoDym Systems. Credit card payment should be available by late 1996. Meanwhile please mail to: NeoDym Systems 15 Nesbitt St. Nepean ON K2H 8C4 Canada Registration will entitle the user to receive technical support, the latest registered version of multiplot/2 and all updates for a period of 1 year. The shareware version is limited to a maximum of 6 lines or data sets and a maximum of 20 points per line. The registered version can handle up to 60 lines and 800 points per line. The registered version does not display the 'NeoDym/unregistered' logo within the chart area. Future versions will include:- -Ability to overlay plots made from different data files so you can spot differences or trends in the shapes of the lines. -Forward and inverse Fourier transforms of input data. -Selection of display options via separate "floating" tool bar. -Display of differences and ratios between selected lines. -Polynomial curve fitting and display of original and fitted curves. Display of residuals. -3 dimensional and 4 dimensional (yes 4!) plots with variable look angle. -Contour plotting. 8 July 1996 Please use the registration form below:- NeoDym Systems MULTIPLOT/2 Registration User's Name: Title (if applicable): Company (if applicable): Street Address line 1: Street Address line 2: Street Address line 3: City: Postal or Zip Code: Country: e-mail address: phone number: Fax Number: Where did you find Multiplot/2?: