			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?:

