Frozen Fish 2: PC/frozenfish_august_1995.bin/bbs/d09xx/d0918.lha/MultiPlot/Docs/MFF2_format.doc

Text File | 1993-10-04 | 26KB | 563 lines

MULTIPLOT FILE FORMAT 2

file version 1
23/6/1993


This file is freely distributable and the file format has been
placed in the public domain.

 ⌐ Alan Baxter 1993
Cambridge University Department of Pathology,
Tennis Court Road,
Cambridge CB2 1QP, UK.



PROBLEMS
This file format is liable to change. Where ever possible,
compatibility will be maintained so that there will be (at least)
some way of converting existing files to future formats.
The behaviour of the default file format will also change.
Currently, loading a default file alters the characteristics of
existing objects (eg titles and axis labels). In the future, it will
change the characteristics of objects created later in the work
session as well. This will (for example) allow definition of a
standard font for all legends or extra text without having to
alter them by hand after creation.

INTRODUCTION
Multiplot accepts a simple ASCII file for input of data. This
file may be written on any text editor or may be generated as
a textfile from a spreadsheet. Multiplot does not choke on the
linefeed/carriage-return of IBM style spreadsheets. The data
must consist of columns of numbers and  need not contain text.
Text heading the file will be ignored and may be used for an
explanatory note. Blank lines or lines of text interrupting the
columns of numbers are interpreted as separating sets of data,
and each set will be plotted individually in, for example, a
different colour or point size. Multiplot saves data in a special
file format called Multiplot File Format 2. MFF2 contains a
header which describes the plot defaults, axes, labels and text.
The body of the file contains columns of data in the format
described above for input. Each row contains values describing
a separate point. Each point may be described by a value for
X, Y, high error in X, low error in X, high error in Y, and low
error in Y. The two left most columns are always X and Y. If
the file contains only 4 columns, the following two columns
may be either high and low errors in X or Y. If the file
contains 6 columns the order is (left to right) X, Y, high error
in X, low error in X, high error in Y, low error in Y. Data
sets are separated by a blank line and a header describing how
the data set is to be rendered and its associated legend. Text
is saved with information describing the font, character size
and screen location. Multiplot XLNf can also read the files
written by the previous version of Multiplot, XLNe.
Unfortunately some information is lost due to incompatibilities,
particularly in the way text is recorded.

NOTES ABOUT FORMAT PRESENTATION
In the example file that follows, any comment lines are
preceded with the character '|'. These lines should not appear
in any MFF2 files, and are only included here for illumination.
The character'/' at the end of a line indicates that the line
was truncated and continues on the following line for
typesetting purposes. In MFF2 files, lines should not contain a
carriage return, and the character '/' does not have this
meaning.

AN EXAMPLE

½║╗MULTIPLOT½║╗ FF2
|   The above line should appear in any MFF2 file.
|   Files without this line can be loaded into Multiplot but
|   should not contain any keywords and cannot be used to
|   define formatting such as axes and additional text.

*AUTOSCRIPT2* 68 1 1 1 1
|   The keyword '*AUTOSCRIPT2*' indicates that the line
|   contains general formatting information and distinguishes
|   (together with the first line) the file from earlier
|    Multiplot file formats.
|   The following 5 digits are of the types:
|   (short) ErrBar: Defines the manner in which the columns
|                  of data encode the points described.
|                  Consists of one of:
|                  0x0001 No Y error bars,
|                  0x0002 Y errors symmetrical, or
|                  0x0004 high and low asymmetrical error |
                     bars.
|                  anded to one of:
|                  0x0010 No X error bars,
|                  0x0020 X errors symmetrical, or
|                  0x0040 high and low asymmetrical error |
                     bars.
|          eg: 0x0011 x values in column 1, y in column 2
|              0x0041 columns are (from left) x, y, high x
|                     error, low x error.
|          NOTE: 0x0002 and 0x0020 are not yet supported and
|          are included for future expansion.
|   (short) ShowErr: Sets Y error bars on or off without
|                  loosing data. One of:
|                  1 On
|                  0 Off
|          NOTE: Other values reserved for expansion.
|   (short) ShowXErr Sets Y error bars on or off without
|                  loosing data. One of:
|                  1 On
|                  0 Off
|          NOTE: Other values reserved for expansion.
|   (short) Grid: Defines graph axis format. One of:
|                  0 No axes
|                  1 Stem and Leaf, left and bottom edges
|                  2 Box axes
|                  3 Stem and Leaf, floating origin.
|          NOTE: 3 is not yet supported and is included for
|          future expansion. Other values reserved for
|          expansion.
|   (short) RMargin: Flag indicates if margin should be left
|                  for legends or not. One of:
|                  0 No right margin
|                  1 Leave right margin.
|          NOTE: This flag may be adapted to describe the
|          margin more precisely in the future. For optimum
|          compatibility, use the value 0.
|   (short) Mode Indicates the program mode. One of:
|                  0 Plotmode
|                  1 Statistics mode
|          NOTE: The flag is not yet utilised. Higher values
|          are reserved for future expansion.

*TITLE* 32907 64187 topaz.font 8 This is the Title
|   The keyword '*TITLE* indicates that the line contains
|   a description of the position, font and text of the title
|   of the plot. The keyword is followed by:
|   (int) PosHoriz Describes the horizontal position of the text
|                  from the left edge of the graph to the
|                  centre of the text in unit lengths which are
|                  1/65535 of the full width of the graph.
|   (int) PosVert  Describes the vertical position of the text
|                  from the top edge of the graph to the
|                  centre of the text in unit lengths which are
|                  1/65535 of the full hight of the graph.
|   (char) FontName[] Text describing the font.
|   (short)FontSize Describes the vertical font size in pixels.
|   (char) Title[] The remainder of the line contains the text
|                  which is to be used for the title.
|          NOTE: All additional extension will take place
|          between FontSize and Title[].

*XAXISDAT* 10 0 1 1 0 1 -1.00000e+01 5.10000e+01 0 0 0 11/
topaz.font 8
|   The keyword '*XAXISDAT*' indicates that the line
|   describes features of the X Axis, including scale type,
|   tics, range and axis values. The keyword is followed by:
|   (short) Nbigtics Describes the number of major subdivisions
|                  on the axis.
|   (short) Bigticlines Describes the subdivision marker for
|                  major subdivisions. One of:
|                  0 Use tic marks.
|                  1 Solid line for grid.
|                  2-6 Selects grid line pattern.
|   (short) Bigticcolour Describes the colour of the
|                  subdivision marker for major subdivisions.
|                  The integer describes the number of the
|                  colour from the palette.
|           NOTE: Currently limited to 0-15, but subject to
|           change almost immediately. Is very likely to require
|           further alteration to accommodate 24 bit palettes.
|   (short) Nsmltics Describes the number of minor
|                  subdivisions on the axis.
|   (short) Smlticlines Describes the subdivision marker for
|                  minor subdivisions. One of:
|                  0 Use tic marks.
|                  1 Solid line for grid.
|                  2-6 Selects grid line pattern.
|   (short) Smlticcolour Describes the colour of the
|                  subdivision marker for minor subdivisions.
|                  The integer describes the number of the
|                  colour from the palette.
|           NOTE: Currently limited to 0-15, but subject to
|           change almost immediately. Is very likely to require
|           further alteration to accommodate 24 bit palettes.
|   (double) Min Describes the minimum range of the axis.
|   (double) Max Describes the maximum range of the axis.
|   (short) AxisType Defines the type of axis. One of:
|                  0 Linear
|                  1 Logarithmic
|                  2 Category (for scatter graphs)
|           NOTE: Expansion will include definitions for
|           statistical plot types: box plot, box graph and
|           histogram.
|   (short) ValuesLock Locks axis values preventing Multiplot
|           automatically rewriting them. One of:
|                  0 Off
|                  1 On
|           NOTE: For maximum future compatibility, use '0'
|           if possible.
|   (short) RegionLock Locks axis scale preventing Multiplot
|           automatically rescaling. One of:
|                  0 Off
|                  1 On
|           NOTE: For maximum future compatibility, use '0'
|           if possible.
|   (short) Valno Describes the number of values on the axis.
|           Is used to obtain the number of lines containing
|           text location and content which follow the
|           'AXISDAT' line.
|           NOTE: this value MUST correctly identify the
|           number of text descriptor lines that follow. For
|           flexibility, this value is not assumed to be the
|           same as the number of subdivisions.
|   (char) FontName[] Text describing the font.
|   (short) FontSize Describes the vertical font size in pixels.

           6824 3429 -10
|   Following the '*XAXISDAT*' line is a number of lines
|   which describe the locations and text of the axis values.
|   Each line consists of:
|   (int) PosHoriz Describes the horizontal position of the text
|                  from the left edge of the graph to the
|                  centre of the text in unit lengths which are
|                  1/65535 of the full width of the graph.
|   (int) PosVert  Describes the vertical position of the text
|                  from the top edge of the graph to the
|                  centre of the text in unit lengths which are
|                  1/65535 of the full hight of the graph.
|   (char) Text[] The remainder of the line contains the text
|                  which is to be used for the value.
|           NOTE: All additional extension will take place
|           between PosVert and Text[]. The font and size are
|           described for all values on the axis in the
|           '*XAXISDAT*' line.

           12340 3429 -3.9
           17856 3429 2.2
           23371 3429 8.3
           28887 3429 14.4
           34403 3429 20.5
           39919 3429 26.6
           45435 3429 32.7
           50950 3429 38.8
           56466 3429 44.9
           62075 3429 51

|           NOTE: The total number of text descriptor lines is
|           equal to the value of Valno in the '*XAXISDAT*'
|           line.

*XLABEL* 34403 1592 topaz.font 8 This is the X Label
|   The keyword '*XLABEL*' indicates that the line contains
|   a description of the position, font and text of the label
|   for the X Axis. The keyword is followed by:
|   (int) PosHoriz Describes the horizontal position of the text
|                  from the left edge of the graph to the
|                  centre of the text in unit lengths which are
|                  1/65535 of the full width of the graph.
|   (int) PosVert  Describes the vertical position of the text
|                  from the top edge of the graph to the
|                  centre of the text in unit lengths which are
|                  1/65535 of the full hight of the graph.
|   (char) FontName[] Text describing the font.
|   (short)FontSize Describes the vertical font size in pixels.
|   (char) Label[] The remainder of the line contains the text
|                  which is to be used for the title.
|          NOTE: All additional extension will take place
|          between FontSize and Label[].

*YAXISDAT* 1 10 0 1 1 0 1 2.70000e+01 5.30000e+01 0 0 0 11/
topaz.font 8
|   The keyword '*YAXISDAT*' indicates that the line
|   describes features of the Y Axis, including position, scale
|   type, tics, range and axis values. The keyword is followed
|    by:
|   (short) Position Defines whether the Y axis is positioned to
|                  right or left of the plot. One of:
|                  1 Left.
|                  3 Right.
|           NOTE: No other values are acceptable. The order
|           of multiple Y axes is indicated by the order they
|           are listed in the MFF2 file, with the lower most
|           axes defined first.
|   (short) Nbigtics Describes the number of major subdivisions
|                  on the axis.
|   (short) Bigticlines Describes the subdivision marker for
|                  major subdivisions. One of:
|                  0 Use tic marks.
|                  1 Solid line for grid.
|                  2-6 Selects grid line pattern.
|   (short) Bigticcolour Describes the colour of the
|                  subdivision marker for major subdivisions.
|                  The integer describes the number of the
|                  colour from the palette.
|           NOTE: Currently limited to 0-15, but subject to
|           change almost immediately. Is very likely to require
|           further alteration to accommodate 24 bit palettes.
|   (short) Nsmltics Describes the number of minor
|                  subdivisions on the axis.
|   (short) Smlticlines Describes the subdivision marker for
|                  minor subdivisions. One of:
|                  0 Use tic marks.
|                  1 Solid line for grid.
|                  2-6 Selects grid line pattern.
|   (short) Smlticcolour Describes the colour of the
|                  subdivision marker for minor subdivisions.
|                  The integer describes the number of the
|                  colour from the palette.
|           NOTE: Currently limited to 0-15, but subject to
|           change almost immediately. Is very likely to require
|           further alteration to accommodate 24 bit palettes.
|   (double) Min Describes the minimum range of the axis.
|   (double) Max Describes the maximum range of the axis.
|   (short) AxisType Defines the type of axis. One of:
|                  0 Linear
|                  1 Logarithmic
|                  2 Category (for scatter graphs)
|           NOTE: Expansion will include definitions for
|           statistical plot types: box plot, box graph and
|           histogram.
|   (short) ValuesLock Locks axis values preventing Multiplot
|           automatically rewriting them. One of:
|                  0 Off
|                  1 On
|           NOTE: For maximum future compatibility, use '0'
|           if possible.
|   (short) RegionLock Locks axis scale preventing Multiplot
|           automatically rescaling. One of:
|                  0 Off
|                  1 On
|           NOTE: For maximum future compatibility, use '0'
|           if possible.
|   (short) Valno Describes the number of values on the axis.
|           Is used to obtain the number of lines containing
|           text location and content which follow the
|           'AXISDAT' line.
|           NOTE: this value MUST correctly identify the
|           number of text descriptor lines that follow. For
|           flexibility, this value is not assumed to be the
|           same as the number of subdivisions.
|   (char) FontName[] Text describing the font.
|   (short) FontSize Describes the vertical font size in pixels.
|           NOTE: Multiple Y axis structures may be defined.
|           Each should have the axis value descriptors follow
|           the '*YAXISDAT*' line, and optimally, should have
|           value descriptor lines followed by a '*YLABEL*'
|           line describing the axis label.

           5048 2939 27
|   Following the '*YAXISDAT*' line is a number of lines
|   which describe the locations and text of the axis values.
|   Each line consists of:
|   (int) PosHoriz Describes the horizontal position of the text
|                  from the left edge of the graph to the
|                  centre of the text in unit lengths which are
|                  1/65535 of the full width of the graph.
|   (int) PosVert  Describes the vertical position of the text
|                  from the top edge of the graph to the
|                  centre of the text in unit lengths which are
|                  1/65535 of the full hight of the graph.
|   (char) Text[] The remainder of the line contains the text
|                  which is to be used for the value.
|           NOTE: All additional extension will take place
|           between PosVert and Text[]. The font and size are
|           described for all values on the axis in the
|           '*YAXISDAT*' line.

           4300 8942 29.6
           4300 14944 32.2
           4300 20946 34.8
           4300 26948 37.4
           5048 32951 40
           4300 38953 42.6
           4300 44955 45.2
           4300 50958 47.8
           4300 56960 50.4
           5048 62962 53

*YLABEL* 1028 33931 topaz.font 8 This is the Y Label
|   The keyword '*YLABEL*' indicates that the line contains
|   a description of the position, font and text of the label
|   for the Y Axis which is described immediately previously.
|   The keyword is followed by:
|   (int) PosHoriz Describes the horizontal position of the text
|                  from the left edge of the graph to the
|                  centre of the text in unit lengths which are
|                  1/65535 of the full width of the graph.
|   (int) PosVert  Describes the vertical position of the text
|                  from the left edge of the graph to the
|                  centre of the text in unit lengths which are
|                  1/65535 of the full hight of the graph.
|   (char) FontName[] Text describing the font.
|   (short)FontSize Describes the vertical font size in pixels.
|   (char) Label[] The remainder of the line contains the text
|                  which is to be used for the title.
|          NOTE: All additional extension will take place
|          between FontSize and Label[].

*AUTOSET2* 1 2 1 8 6 1 0
|   The keyword '*AUTOSET2*' indicates that the line
|   describes the display options of a data set, the individual
|   points of which are to follow. The keyword is followed by:
|   (short) Colour Describes the colour of the points and lines
|                  Used to render the data set. The integer
|                  describes the number of the colour from the
|                  palette.
|          NOTE: Colour values higher than 16 are currently
|          expressed as the value modulo 16. This behaviour
|          will change.
|   (short) PlotType Describes the method used to render the
|                  data set. One of:
|                  0 Line only
|                  1 Points only
|                  2 Points and Lines
|                  3 Step graph (survival curve)
|                  4 Impulse plot
|                  5 Bar graph
|                  6 Histogram
|          NOTE: Option '6' is not yet supported. All higher
|          values reserved for future expansion.
|   (short) Lines Describes the line pattern used for
|                  line plots, impulse plots and histograms.
|                  One of:
|                  0 No lines
|                  1 Solid line.
|                  2-6 Selects grid line pattern.
|          NOTE: The value '0' is currently redundant and may
|          be used for some other purpose in the future. The
|          line pattern numbers used here correspond to the
|          same patterns as those used for the grid lines.
|   (short) PointSize Hight in pixels of the points
|   (short) PointType Describes the point shape. One of:
|                  1 Triangle
|                  2 Diamond
|                  3 Cross (x)
|                  4 Star (*)
|                  5 Cross (+)
|                  6 Box
|          NOTE: Higher values are reserved for future
|          expansion.
|   (short) Enabled Describes whether this data set should be
|                  plotted or not. Enables 'hidden data' to
|                  remain in a data file without cluttering
|                  up the plot. One of:
|                  0 Not plotted.
|                  1 Plotted.
|   (short) YAxis Identifies the Y axis this data set is
|                  associated with. Y axes are numbered from
|                  0 and in the order they appear in the MFF2
|                  file.

*LEGEND* 61515 49120 topaz.font 8 King Arthur
|   The keyword '*LEGEND*' indicates that the line contains
|   a description of the position, font and text of the legend
|   for the data set described immediately previously and the
|   points of which follow. The keyword is followed by:
|   (int) PosHoriz Describes the horizontal position of the text
|                  from the left edge of the graph to the
|                  centre of the text (including data set
|                  identifier) in unit lengths which are
|                  1/65535 of the full width of the graph.
|   (int) PosVert  Describes the vertical position of the text
|                  from the left edge of the graph to the
|                  centre of the text in unit lengths which are
|                  1/65535 of the full hight of the graph.
|   (char) FontName[] Text describing the font.
|   (short)FontSize Describes the vertical font size in pixels.
|   (char) Legend[] The remainder of the line contains the
|                  text which is to be used for the title.
|          NOTE: All additional extension will take place
|          between FontSize and Label[].

0.00000e-01 5.10630e+01 1.36770e+00 1.36770e+00 1.36770e+00/
1.36770e+00
|   This line describes the first point in the first data set.
|   It contains the following:
|   (double) X value
|   (double) Y value
|   (double) high error in X
|   (double) low error in X
|   (double) high error in Y
|   (double) low error in Y
|          NOTE: The number of columns and their meaning
|          varies depending on the value of ErrBar in the
|          '*AUTOSCRIPT2*' line.

2.00000e+00 5.09440e+01 1.36630e+00 1.36630e+00 1.36630e+00/
1.36630e+00
4.00000e+00 4.94260e+01 1.34960e+00 1.34960e+00 1.34960e+00/
1.34960e+00
6.00000e+00 5.02140e+01 1.35820e+00 1.35820e+00 1.35820e+00/
1.35820e+00
8.00000e+00 4.90640e+01 1.34550e+00 1.34550e+00 1.34550e+00/
1.34550e+00
1.00000e+01 5.02730e+01 1.35890e+00 1.35890e+00 1.35890e+00/
1.35890e+00
1.20000e+01 4.81830e+01 1.33560e+00 1.33560e+00 1.33560e+00/
1.33560e+00
1.40000e+01 4.90560e+01 1.34530e+00 1.34530e+00 1.34530e+00/
1.34530e+00

|   The remainder of data set 1 has been deleted.


*AUTOSET2* 2 2 1 8 5 1 0
1.00000e+00 3.12140e+01 1.13140e+00 1.13140e+00 1.13140e+00
1.13140e+00
3.00000e+00 3.11210e+01 1.12990e+00 1.12990e+00 1.12990e+00
1.12990e+00
5.00000e+00 3.09360e+01 1.12700e+00 1.12700e+00 1.12700e+00
1.12700e+00
7.00000e+00 3.08950e+01 1.12640e+00 1.12640e+00 1.12640e+00
1.12640e+00
9.00000e+00 3.14240e+01 1.13470e+00 1.13470e+00 1.13470e+00
1.13470e+00
1.10000e+01 3.15980e+01 1.13750e+00 1.13750e+00 1.13750e+00
1.13750e+00
|   The remainder of data set 2 and all following data sets
|   have been deleted.

*EXTRATEXT* 42069 18374 topaz.font 8 Silly Text
|   The keyword '*EXTRATEXT*' indicates that the line
|   contains a description of the position, font and text of a
|   line of additional text. The keyword is followed by:
|   (int) PosHoriz Describes the horizontal position of the text
|                  from the left edge of the graph to the
|                  centre of the text in unit lengths which are
|                  1/65535 of the full width of the graph.
|   (int) PosVert  Describes the vertical position of the text
|                  from the top edge of the graph to the
|                  centre of the text in unit lengths which are
|                  1/65535 of the full hight of the graph.
|   (char) FontName[] Text describing the font.
|   (short)FontSize Describes the vertical font size in pixels.
|   (char) Text[] The remainder of the line contains the text
|                  which is to be used.
|          NOTE: All additional extension will take place
|          between FontSize and Text[]. All extra text must be
|          defined at the end of the MFF2 file.
|   THE EXAMPLE ENDS HERE.
|   No special character is needed to indicate the end of a
|   data file.

THE DEFAULT FILE FORMAT
The default file format is based on the header of the MFF2
file. The only difference is that it is proceeded by 16 lines
which define the palette settings and line widths for each pen.
Each of the first 16 lines consists of 4 shorts. The first 3
describe the red, green and blue components (in that order) of
the colour used for both screen representation and (where
supported) printed output. The fourth short indicates the line
thickness of lines generated by that pen when printed.
Following the pen definitions are lines from the MFF2 file
header:
½║╗MULTIPLOT½║╗ FF2
*AUTOSCRIPT2*
*XAXISDAT*
*XLABEL*
*YAXISDAT*
*YLABEL*
Multiple Y axes are indicated by defining them sequentially.
The format of the default file is liable to change in the future
to incorporate a way of defining default fonts for legends and
extra text, and default point sizes, line types etc. This will be
achieved by utilising other keywords from the MFF2 file format.