gd file format


This is the complete description of the gd input file format.
In general the format is free, i.e. where spaces are used as separators
it doesn't matter how many of them you use. Tabs are accepted and replaced
by a single space. Empty lines are ignored.
Both UNIX- and DOS-style line separators are supported which means that
you can edit files on DOS-based PCs and plot them on computers running the UNIX version of gd.
Files in compressed format are also supported, see command GREAD


1. Title of the plot

   This is a text line which must appear as first line in the file.
   Example:

   Fission barriers of Ac isotopes


2. Description of the x-axis

   Optional, may appear in any line. Example:

   X: neutron number

   an additional minus sign inverts the x-axis:

   X-: neutron number


3. Description of the y-axis

   Optional, may appear in any line. Example:

   Y: Bf$ / MeV

   an additional minus sign inverts the y-axis

   Y-: Bf$ / MeV


4. Data block headers

   Start blocks of data.
   Lines following data block headers are assumed to be numerical data.
   The number of data block headers and associated data in a file is
   only limited by the amount of memory available.
   A data block header line must begin with H:, H2:, A: or N:
   for 1-dimensional, 2-dimensional, analyzer and ignored data, respectively.
   A particular data block header is valid until the next data block header.
   The meaning and the syntax of the various data block headers are explained in the following.


4.1 1-dimensional data blocks (H:)


   The H: header line describes the type of data following the header line,
   and how they appear in the plot (linemode, colour, symbols).
   Various column types may be specified and the order in which they appear
   determines how the data columns are interpreted.
   Valid column types are X, Y, S, B, A, M, D, N.
   At least an X and a Y must be given.
   Because columns of the same type may appear more than once
   the column type specifiers may be followed by numbers in order to ensure uniqueness.

   X specifies a column of x-values.
     If the x-values are equidistant they may be replaced by a loop expression in parantheses:

     H: (X = 1 TO 100 BY 0.5)  Y,H0





   Y specifies a column of y-values.
     An optional text immediately following in parentheses is interpreted
     as a description of the data and is shown together with the symbol as a legend
     (see the GDESCR: tag below and command GDESCR)
     Example:

     H: Y1(Exp. 1) Y2(Exp. 2)


     The Y column is also the place where to define the presentation of the data.
     After a separating comma you can optionally specify (no additional spaces !):

     Linemode
        A single letter specifies the line mode.
        If no linemode is specified solid lines are assumed.
 
     Data symbols
        Data symbols are defined as numbers.
        If no symbol is specified an open circle is assumed.

     Data processing
        There are various ways to further process the data in addition to merely plotting the data points.
        You can smooth the data or perform an analytic polynomial fit.

     Data presentation
        Additional letters specify various ways of data presentation,
        e.g. histograms, columns, closed polygons and optionally hatched areas.
        If no additional presentation is specified only data symbols and connecting lines are drawn.

     Colour
        Each Y-column can have its own colour specified by
        combinations of red, green and blue components.
        See the section on colour handling.

     Any combination of presentation options in any order is allowed.
     Example:

     H: x y(comment),boo1


   D specifies a column of error-values referring to the X- or Y-column to the left.
     Additional optional modifiers are +, - and %
     to specify positive, negative and percent errors, respectively.
     Example:

     H: x d+  d-  y1 d% y2 d-% y3  d
        1 0.1 0.2 2  5  20 10  200 10.7

     Operations with data columns offer the possibility to assign constant error values:

     H: x (d-=0.1) y  (d%=5)
        1          10
        2          20

     Only the X- and Y-values are defined by data, the errors by assigning
     a constant value of 0.1 (negative errors only) and 5%, respectively.

   S specifies an optional column of factors to modify individually
     the size of the data symbols of the preceeding Y-column.
     S-columns may be modified the same way as Y-columns.
     Example:

     H: X   Y       S
        1   3       0.25
        3   7.3     4.0

     The first data point (x,y)=(1,3) will be plotted with 1/4 of the standard size,
     the second one (x,y)=(3,7.3) with 4 times the standard size.
     If the display parameter SAREA is specified, the area of the
     symbol is scaled. With the display parameter SLOG the log10
     value of the size or the area, respectively, is scaled.
     Additionally, the display parameters SMIN and SMAX may by used
     to scale the size of the symbols.
 
   A specifies a column of y-values which is added to the A-, M- or Y-column to the left.
     A-columns are otherwise treated the same way as Y-columns.
     You use A*-1 to subtract data.
     Example:

     H:  X  Y1 A1 Y2   A2*-1
         1  10 10 100 100
         2  20 10 200 100

     The first A-column is plotted as y=20 and y=30, the second one as y=0 and y=100.

   M specifies a column of y-values which is multiplied with the A-, M- or Y-column to the left.
     M-columns are otherwise treated the same way as Y-columns.
     You use M**-1 to divide data.
     Example:

     H:  X  Y1 M1 Y2  M2**-1
         1  10 10 100 100
         2  20 10 200 100

     The first M-column is plotted as y=100 and y=200, the second one as y=1 and y=2.

   B specifies a column of y-values
     which is used as a polygon boundary for the plotting of 2-dimensional data
 
   N specifies a column which is to be ignored.
     However, the data in this column are checked for validity.

   The X- Y- and N-columns may appear in any order.
   Thus you may easily select part of the data to be shown or you may interchange the x- and the y-values.
   Example:

      H: y  n  x
         1 10 100
         2 20 200
         3 30 300

   is equivalent to:

      H: x   y
         100 1
         200 2
         300 3


   Data columns may be modified by attaching a short arithmetic expression:

   H: Y(Data),L2+200      add 200 to the y-values
   H: X/5                 divide the x-values by 5
   H: Y*10                multiply the y-values by 10
   H: D+-/5               divide the error values by 5
   H: Y**-2*3.5+37.7

   There are more sophisticated ways to perform operations with data columns.
 






 

4.2 2-dimensional data blocks (H2:)

   See Handling of 2-dim data

4.3 Analyzer data blocks (A:)

   See Handling of analyzers

4.4 Ignore data blocks (N: or N2:)

   Specifies the data in the following lines to be ignored up to the next data block header
 

4.5 Pseudo 3-dimensional data

   are specified the same way as 1-dimensional data,
   but with an extra z-column. Thus scattered data can be plotted,
   as symbols of either different size or different colour.
   Example:

   H: x y z(z),12 n(y),l2 
   1 1 2    1.5 
   2 2 4    2.0
   3 3 6    2.5

   The z-values will be plotted as symbols of type 12 of different size.
   Coloured symbols can be obtained for example with the display parameter
   cuts(1,3,5,7).
   Additionally the parameter
   2dcolour()
   may be used.
   
5. Data lines after header lines

   After header lines you normally specify the data values corresponding
   to the columns identified in the header.
   You must provide as many data values in an input line as there are columns in the header line.
   Data are entered in free format. If you specify more data than needed the extra data are ignored.
   You may "simulate" an end-of-line by a semicolon (;):

   H: x   y1   y2
      124 6.60 11.11
      126 6.57 11.94

   is equivalent to

   H: x   y1   y2
      124 6.60 11.11; 126 6.57 11.94

   If a semicolon would appear after each number it may be omitted.

   Sometimes it may be useful to leave out single data items,
   e.g. experimental data which have not been measured yet.
   A double minus (--) instead of a numerical data item causes the corresponding coordinate pair to be ignored:

   H: x   y1   y2
      124 6.60 11.11
      126 --   11.94

   only the y2-column is plotted completely, from the y1-column only the
   coordinate pair (124,6.60) is displayed.
   Like data specified as -- also Inf and NaNQ are ignored.

   Data lines in a data block may be mixed with interspersed
   comments (C:), text (W:) or display parameters (P:).
 

6. Comment line (C:)

   A line starting with C: specifies data to be ignored. Example:

   C: Data of ref. (DaS78)


7. Text to be written on the plot (optional),(W:)

   A line starting with W: specifies text to be written on the plot.
   Example:

   W: Hello world / xrel(0.5) yrel(0.5)

   specifies that the text " Hello world " is written
   with the lower left corner placed in the middle of the area defined by the coordinate axes.

   The W: tag is handled like a command and most parameters are the same as for the command GWRITE.
   The syntax is as follows:

                  Default
   W: text      
      /
      X(x)      
      Y(y)      
      XREL(xr)  
      YREL(yr)  
      ANGLE()   
      SIZE()    
      CMODE()   

      POSITION()
      WIDTH()    0.1
      SPACING()  1
      ROTATE()   0
      LENGTH()   1
      COLOUR()  
      HUE()     
      CLIPPING()
      SX()      
      SY()      

      LL()      
      LLX()     
      CONTINUE  
      BREAK     
      NEXT()    
      LINEDIST()
      FORMAT()  

   Parameter values which are omitted, are inherited from one W:-line to the next.


8. Display parameters for the plot or display (optional) (P:)

   A line starting with P: specifies additional parameters
   which affect the layout of the picture. An arbitrary number of
   P:-lines may be specified. Any display parameter may be specified.
   Display parameters may also be specified with the commands GDISP, GPLOT,  GPRESET.
   The actual representation may be saved with the command GSAVE.

   Example:

   P: XLIN SCA(1.2) FORMAT(0.8)


9. Graphic elements (optional) (E:)

   A line starting with E: specifies a graphic element
   (such as lines, arrows, geometric figures etc.)
   Example:

   E: arrow( 125, 7, 5, 1, 30, 0, g )

   specifies a green arrow symbol with the tip at (x,y)=(125,7).

   See graphic elements for more details and a list of possible elements.

10. Legend (optional) (GDESCR:)

   A line starting with GDESCR: specifies the location and layout of a legend (description) of the data columns.
   Example:

   GDESCR: xrel(0.5) yrel(0.5) frame

   specifies that the upper left corner of the description is placed in the middle of the area
   defined by the coordinate axes. A frame is drawn around the text and the
   area within the frame is cleared before filling it with text and symbols.

   The parameters of the GDESCR: tag are the same as for the command GDESCR

11. Included data sets (optional) (INBED:)

   A line starting with INBED: specifies a file to be included inline.
   Example:

   INBED: include.gd

   See including files for more details


12. Text replacement ($1,$2,$3,$4,$5,$6,$7,$8)

   Sometimes it might be useful to fill parts of the input file dynamically at the time the data are read.
   Therefore a text replacement facility is available.
   You can put up to eight placeholders $1, $2, $3, $4, $5, $6, $7 or $8 in the text.
   When read they are ignored (replaced by null strings) unless
   you specify a replacement text as part of the GREAD command.
   For example a file sample.gd:

   H: x y$2
      1 10
      2 20

   read and displayed with

   gread sample.gd
   gdisp

   will show the (x,y) = (1,10) and (2,20), whereas

   gread sample.gd *2
   gdisp

   will show the (x,y) = (1,20) and (2,50).