Extend

Home ] Up ] General ] Short ] Syntax ] Postscript ] Hints ] Cursor ] DSN ] Arithmetik ] Line Modes ] Colours ] Polar ] 2Dim ] 3Dim ] Analyzers ] Library ] Types ] Text ] Graphic ] Inbed ] Fit ] Presentation ] [ Extend ] Concepts ] Dynamic ] Listmode ] Macros ] Goosydata ] Online ] Commands (List) ] Commands (Details) ] Install ] MSWindows ] Problems ]

GSI
FRS

 

 

SATAN Help
EXTENDED ANALYSIS:  

Analyzers and pseudoanalyzers
  
GRAF provides several features for an extended data analysis
using analyzers and pseudoanalyzers.
Analyzers are defined by the macro AGEN in the analysis 
program (see also HELP MACROS) or the command AGEN. 
Try the following sequence in SATAN:
"AGEN TEST / DIM(1) LIMITS(1,100) BIN(1)"
This command creates a 1-dimensional analyzer with 100 channels.
"ASET TEST = 10"
This command fills all channels of the analyzer TEST with 10 counts.
"ASET TEST = 20 / LIMITS(50,60)"
This command fills channels 50 to 60 with 20 counts.
"GDISP TEST"
This command draws the analyzer TEST on the screen.       
Pseudo analyzer may be created from the data of specifically 
selected data columns in a GRAF dataset. The first Y data 
column following the header specification A: or A2:, 
respectively, (instead of H:  or H2:) is interpreted as a 
pseudo analyzer.
Try the following:
Create a dataset TEST.GRF as a text file. (You might first create a
dataset named TEST.TXT and then rename it.)
Enter the following lines in this dataset:
 TEST
 X: Channel
 Y: Counts
 A:   X    Y,HT0
      1     1.2
      2.5   4.38
      3     9.1
      5     6.9
      7.5   4.5
Start SATAN in the same directory in a DOS window and enter the
following commands:
"GREAD TEST"
 This command reads the data of the pseudoanalyzer.
"GDISP"
 This command draws the pseudoanalyzer on the screen.      
Pseudo analyzers may have equidistant or non-equidistant x 
values. According to the presentation of the data defined in 
the dataset, the analysis differentiates between continuous 
distributions (presented as histograms) and discrete data 
points (presented by data symbols or/and lines).  Note that 
operations (e. g. fits) with these two different data types 
may give different results! analyzers are normally defined as 
continuous distributions. They always have equidistant x 
values.
Try the following:
Change the line "A:   X    Y,HT0" in the above given pseudo analyzer
to the following: "A:   X    Y,LT1"
Start SATAN in the same directory in a DOS window and enter the 
following commands:
GREAD TEST
This command reads the data of the pseudoanalyzer.
GDISP
This command draws the pseudoanalyzer on the screen.
Instead of an histogram (a continuous distribution) you now see
datapoints (discrete values).
     
Display points, windows and conditions
      
The following features may be defined in the dataset 
(presented in examples ==>):
==> P1: A 34
defines the display point named A for the x value 34 in a 
one-dimensional data array.
==> W1: C 30.4 37.5
defines the window named C with the limits 30.4 and 37.5 in a 
one-dimensional data array. The analysis of display points 
and windows (height, sum, etc.) may be shown on the display by 
the commands PDISP * and WDISP *, respectively. The result is 
also stored to the dataset in the following form with the 
command GSAVE:
==> P1: A 34  => CONTENT(879)
==> W1: C 30.4 37.5 => SUM(98634) MEAN(32.986) SIGMA(2.793)
Also two-dimensional polygon windows may be defined in the 
dataset:
==> W2: FISSION  X  Y
    315,413;327,440;317,403;300,410
      
 
The following list gives examples of extended commands which 
are available for ANALYZERS. (Use "HELP commandname" for more 
information.) Some of these commands also work with PSEUDO 
ANALYZERS, sometimes with a few restrictions.
      
 
Display of analyzers

      
  GDISP   anlid  / ...                display analyzer

  GEXPAND                             expand in x and y direction

  GXEXPAND                            expand in x direction

  GYEXPAND                            expand in y direction
    GEXPAND, GXEXPAND and GYEXPAND   are also supported for a 
                                     combination of displayed 
                                     analyzers, drawn by several GOVER 
                                     commands. Only the specific 
                                     analyzer which is identified by 
                                     the cursor position is expanded.
    usage of GEXPAND, GXEXPAND, GYEXPAND:
        GEXPAND                    demands for the cursor to be positioned
        GEXPAND  10 200 500 900    expands region given by the numbers

  GCOMLIST  text / ADD  CLEAR  LIST ON OFF
                                     handle comment for plot or display
    GCOMLIST text            writes the "text" to the actual picture,
                               the "text" is not added to the comment 
                               list
    GCOMLIST text / add     adds the "text" to the comment list
    GCOMLIST / LIST         lists the actual comment list
    GCOMLIST                 writes the comment list to the current 
                               picture
    GCOMLIST / CLEAR        clears the comment list
    GCOMLIST / ON            after this command, the comment list is 
                               written automatically to each picture
    GCOMLIST / OFF           stops the automatic writing 
      
  Additionally, GOVER, GPLOT, GPRESET etc. may be used.
      
 
Handling of windows, display points and conditions
      
(available for ANALYZERS and PSEUDO ANALYZERS)      
  PSET               set display point

  PDISP             get display point
      
  WDEF (W1DEF)      assign a name to the window or condition

  WSET (W1SET)      set window

  WDISP (W1DISP)    display window

  WLIST (W1LIST)    list window limits and moments of counts in window
        
  W2DEF              assign a name to the window or condition
                      (names with one character or numbers between
                         1 and 999 are not allowed)
  W2SET             set banana window on 2-dim analyzer by cursor

  W2DISP            draw banana window for 2-dim analyzer

  W2MOD              modify banana points

  W2NULL            clear analyzer outside window

  W2LIST            list content and moments of counts in window  
  usage of P.. and W.. commands:
     These commands work only if an analyzer is displayed on the screen.
      
  (The 2-dim. window features are only available for ANALYZERS.)
      
    Windows and points are internally characterized by a character.
    27 windows are predefined: A,B,...X,Y,Z,#.
    If no character is specified, the temporary window # is assumed.
    Conditions are internally characterized by a number.
    They must explicitly be defined by the macro AGEN.
    Only conditions may be used in the analysis program with the
    macro AC. The result of AC for conditions which are not set
    (= open) is always true!!! The result of AC for conditions 
    which are set to be closed is always false.
    Conditions and windows on 1-dim. analyzers consist of 2 limits,
    conditions and windows on 2-dim. analyzers are always polygons
    defined by up to 50 points.
    In all window and point commands, ID may be a name,
       a condition number or a window (or point) character.
      
 
Handling of list-mode data

      
  LINPUT / DSN(...)        start accumulation of list-mode data

  LCONTINUE                restart accumulation

  CTRL/C                   halt accumulation (on VMS)

  press BREAK button of SATAN interface window
			   halt accumulation (on WINDOWS)

  LHALT                    halt accumulation
			     The LHALT command is available during
			     accumulation of list-mode data or
			     during a Monte-Carlo simulation when
			     the INPUT or START command is entered
			     directly, not via an EXEC command list.

  SET / LINPUTPATH(...)   set one or several input paths to be scanned
                              for the input dataset    
           ==> GSET / LINPUTPATH(C:\MUELLER\RUN22\,C:\MUELLER\RUN23\)

  LOUTPUT                   Open output device for writing list-mode data,
                              works in connection with the macro $LOUT
                              in the user-analysis program (see HELP MACROS).
                           The aim of LOUTPUT and $LOUT is to write modified
                             (compressed or pre-analyzed) list-mode data on disk.
                           See HELP LOUTPUT for a full list of parameters 
                             and options. 
      Usage of LOUTPUT: 
      1. Example: (each input file in a different output file)
       open 1. output file             LOUTPUT / DSN(outputfile1) COMMENT(blabla1)
       read 1. input file              LINPUT / DSN(inputfile1)
       eventually push break button to interrupt reading and writing and 
         enter LCONTINUE to continue reading and writing
       close 1. output file            LOUTPUT / CLOSE          
       open 2. output file             LOUTPUT / DSN(outputfile2) COMMENT(blabla2)
       read 2. input file              LINPUT / DSN(inputfile2)
       close 2. output file            LOUTPUT / CLOSE 
       (Normally the command LOUTPUT / CLOSE is not necessary, because the  
        output file is closed by opening a new file and when SATAN is terminated. 
        If you want to read the output file by another program it must be closed. 
        This can also be done explicitely by the command LOUTPUT / CLOSE.)
      2. Example: (several input files in one output file)
       open output file                LOUTPUT / DSN(outputfile) COMMENT(blabla)
       read 1. input file              LINPUT / DSN(inputfile1)
       read 2. input file              LINPUT / DSN(inputfile2)
       read 3. input file              LINPUT / DSN(inputfile3)
       cose output file                LOUTPUT / CLOSE  
 
Handling of MONTE-CARLO simulations
      
  LSTART                    start calculation and accumulation

  LCONTINUE                 restart accumulation

  CTRL/C                    halt accumulation (on VMS)

  press BREAK button of SATAN interface window
			    halt accumulation (on WINDOWS)

  LHALT                     halt accumulation
			     The LHALT command is available during
			     accumulation of list-mode data or
			     during a Monte-Carlo simulation when
			     the INPUT or START command is entered
			     directly, not via an EXEC command list.
 
Handling of analyzers
      
(These commands do not work with pseudo analyzers.)
      
  AATT                     list analyzer attributes
         /COUNTS
           Lists the number of counts in the analyzers
             (this evaluation takes some time.)

  ACDEF                    define condition limits

  ACLEAR                   clear analyzer
	(Specific analyzers may be protected agains ACLEAR by 
	 the command "AMOD analyzer / PROTECTED". This is useful
         if the analyzer contains e.g. a calibration which should be
	 kept.)

  ACONVERT                convert 2-dim. analyzer into an array of
                          1-dim. analyzers by sequential cuts
                          or convert array of 1-dim. analyzers into a
                          2-dim. analyzer
         /CUTS(c)
           Direction of the operation {x,y,x+y,x-y} 
               (for 2-dim -> 1-dim)
         /DIMENSION(c)
           Direction of 1-dim. analyzers with respect to the
           2-dim. destination analyzer {x,y}
            (for 1-dim -> 2-dim)
         /PROJECTION(c)
           Direction of the projection {x,y,x+y,x-y}
            (for 2-dim -> 1-dim)
         /INTO(c)
           Destination analyzer or array of destination analyzers.
         /WINDOWS(c)
           Window or condition id of the 2-dim. input analyzer.
           Consider counts inside window or condition only.
           (Does not work, if an array of 1-dim. analyzers is on input.)
         /LIMITS(c)
           Limits  x1,x2,y1,y2.
           Consider counts inside limits only
           (Does not work, if an array of 1-dim. analyzers is on input.)
     Usage:
       Assume that the 2-dim. analyzer NZ contains nuclide cross
       sections as a function of neutron number (x axis) and atomic
       number (y axis).
       To produce an array N_PER_Z(*) of analyzers (neutron number on x axis,
       proton number as index of the analyzer array) with the isotopic cross 
       sections of all elements:
            ACONVERT NZ / INTO(N_PER_Z(*)) CUTS(X) PROJ(X)
       To produce a series of element distributions with fixed mass (proton
       number on x axis, mass number as index of the analyzer array):
            ACONVERT NZ / INTO(Z_PER_A(*)) CUTS(X-Y) PROJ(Y) 
       To convert an array N_PER_Z(*) of isotopic cross sections into a
       2-dim. analyzer in form of a chart of the nuclides:
            ACONVERT N_PER_Z(*) / INTO(NZ) DIM(X)
       If the directions of CUTS and PROJECTION are identical, it is 
       sufficient to specify one of these.
     Remark: The command ACONVERT also supports the functionality of APROJECT.
             The separation into two commands is done for clarity.
  ADECON                   deconvolute a spectrum
    (From a given source analyzer, the contribution of a response 
     analyzer, assumed as a convolution, is removed. The source 
     analyzer may be 1-dimensional or 2-dimensional. In the second 
     case, the deconvolution is performed in the direction of the DIM 
     parameter of the ADECON command. The result is written to a 
     destination analyzer. 
     If the response depends on the amplitude of the signal, a 
     two-dimensional response analyzer must be given; if the response 
     is the same for all amplitudes, a one-dimensional response 
     analyzer is sufficient.
     Per default, a one-dimensional response analyzer is normalized,
     before it is used for deconvolution. 
     The Check analyzer contains the reconvolution of the destination 
     analyzer and the response analyzer. It should be close to the 
     source analyzer.
     Limits and binsizes of the different analyzers must fit to each 
     other.
     The parameter RANGE(i) specifies the number of neighboring 
     channels on each side to be taken into account for correcting the 
     actually processed spectrum element. i = 0 corresponds to the 
     quotient method and is appropriate for spectra containing many 
     peaks. For i > 0, weighting is in effect working best for 
     continuous spectra.)  

  ADESTROY                 destroy dynamically created analyzer

  ADIFF                    build differential of analyzer
                           (The differenced of adjacent channels
                            of the input analyzer are stored in
                            the output analyzer. ADIFF is the
                            inversion of AINT.)

  ADUMP                    dump analyzer to dataset

  GSET / ADUMPPATH(...)   set path for dumping analyzers

  AFPEAK                   automatic peak search in 1-dim. spectrum
                           (see detailed description below)

  AFETCH                   fetch analyzer from dataset
    (ASCII and binary data formats are supported by ADUMP and AFETCH,
     ASCII format: can be edited, data are compressed; 
     binary format: access is very fast, but data need more space,
     in binary format the analyzer can be dumped and fetched only as a 
     whole, interrupt of AFETCH by the BREAK button is enabled)  

  GSET / AFETCHPATH(...)  set path or list of paths for fetching 
                            analyzers

  AGEN                     generate 1-dim. or 2-dim. analyzer
                          (supports arrays of analyzers up to 5 
                          dimensions:
                           ==> AGEN TEST(2:7,15,1000:1300)) LIMITS(1,100);

  AGET                     get contents of an analyzer channel
                          (If the channel value does (resp. values do) 
                          not coincide with the lower limit of a bin, 
                          an interpolated value is returned.)

  AINT                     build integral of analyzer
                          (inversion of ADIFF)

  AIMAGE                   perform linear transformation of 2-dim 
                          analyzer. (Source and destination analyzers 
                          may have different limits and binsizes.)

  ALIST                    list analyzer contents

  AMIRROR                  create mirror image

  AMODIFY                  modify analyzer attributes

  AMODIFY A1 / ATT(A2) defines the values in analyzer A2 as
                                  errors of the analyzer A1

  AMOVE                    move contents of an analyzer

  ANAL                     define dynamic accumulation process using data
                            from event parameters or analyzers.
                          (If the destination analyzer does not yet 
                          exist, it is created with default options.
                          The properties of the destination analyzer may
                          be modified by the command AMODIFY.)
      usage:   ANAL ADEST / E(ITOF) 
                 (The event parameter ITOF of the $EVENT or $GOOREAD macro is 
                  accumulated in the one-dimensional spectrum ADEST)
               ANAL ADEST2 / A(E_MUSIC(1)) A(TWIN_TOF(2),1)
                 (The data of the analyzer MUSIC(1) and of the first dimension of
                  the analyzer TWIN_TOF(2) are accumulated in the two-dimensional
                  spectrum ADEST2.)
               ANAL / LIST    
                 (gives a list of dynamic accumulations)
               ANAL ADEST / DELETE   
                 (removes the analyzer ADEST from the accumulation list)

  ANORM                    normalize analyzer data

  AOPER                    perform arithmetic operations with analyzers,
                           also convolution of 1-dim. analyzers is 
                           supported.   

  APOLISH                  Eliminate fluctuations in analyzer data, due 
                            to missing parts or spurious background peaks.
         /LIMITS(x1,x2) 
           Consider only the part of the spectrum within the given limits. 
         /ZEROES 
           Include channels with zero content to the procedure. By default,
           these channels are not considered.
         /FWHM(r)
           Before any further treatment, the spectrum is smoothed by
              averaging a number of neighboring channels. This option is useful 
              to eliminate or reduce statistical fluctuations or to make the 
           further treatment insensitive to a fine structure in the spectrum.
         /MAXIMUM
           Assume that the original spectrum has negative curvature everywhere.
           (If the parameter CURVATURE(r) is specified, only curvatures below 
           this limiting value are allowed. See also below.)
           That means that peaks are considered to be true, dips are considered
           to be due to missing counts in some localized regions. Regions of the
           spectrum which would lead to negative curvature are disregarded.
         /MINIMUM
           Assume that the original spectrum has positive curvature everywhere.
           (If the parameter CURVATURE(r) is specified, only curvatures above
           this limiting value are allowed. See also below.)
           That means that dips are considered to be true, peaks are considered
           to be due to some localized background. Regions of the spectrum which
           would lead to positive curvature are disregarded. 
         /CURVATURE(r)
           The value r specifies a value for the limiting curvature used in 
           the /MIN or /MAX option. Default value is zero.
         /INTERPOLATION
           The regions of the spectrum which are disregarded due to the /MAX or
           /MIN option are obtained by interpolation of the neighboring points.
         /POLYNOM(i)
           The resulting spectrum is represented by polynomial of degree "i". 
         /SMOOTH(r)
           If a value is given for this parameter, the regions of the spectrum
           which are disregarded due to the /MAX or /MIN option are obtained by
           smoothing on the basis of the rest of the spectrum. The parameter r
           gives the allowed deviations of the smoothed curve from the data 
           points.
         /STATISTICS
           Assume that the data points have statistical uncertainties
           due to Poisson statistics. This determines the weights of the
           data points for the polynomial and the smoothing options.
         /DESTINATION(c) 
           Gives the name of the destination analyzer to which the resulting
           "polished" spectrum is written.
       

  APROJECT                project 2-dim. analyzer onto 1-dim. analyzer

         /DIMENSION(c)
           Direction of the operation, x, y, x+y and x-y.
         /ONTO(c)
           Destination analyzer
         /WINDOWS(c)
           Window or condition id of the 2-dim. input analyzer.
           Consider counts inside window or condition only.
         /LIMITS(c)
           Limits  x1,x2{,y1,y2}.
           Consider counts inside limits only
     Usage:
       Assume that the 2-dim. analyzer NZ contains nuclide cross
       sections as a function of neutron number (x axis) and atomic
       number (y axis).
       To project the isotopic cross sections of Z = 80 on analyzer Z80:
            APROJECT NZ / ONTO(Z80) DIM(X) LIMITS(0,200,80,80)
       To produce a mass distribution:
            APROJECT NZ / ONTO(A) DIM(X+Y)
     Remark: The command APROJECT also supports the functionality of ACONVERT.
             The separation into two commands is done for clarity.

  ARIDGE                   find ridge line in 2-dim. analyzer
  The ridge line of a 2-dimensional distribution is analyzed and stored
  into a 1-dimensional analyzer. The procedure consists of two parts:
      1: Loop over one dimension to determine the ridge points in the 
              other dimension by one of the following methods:
         a) Arithmetic mean
         b) Peak search
         c) Cursor input 
      2: Parameterization of the ridge line by one of the following 
         methods:
         a) Polynomial (degree can be specified)
         b) Smoothing (weight can be specified)
         c) Interpolation 
      (The mathematical methods applied in ARIDGE do not rigorously 
       follow the correct treatment of error propagation. Instead, a 
       more hand-waving procedure is applied which was found to give 
       best results in several test cases.)

  ASET                     set contents of analyzer to required value

  ASHIFT                   shift 2-dim analyzer by data of 1-dim 
                          analyzer

  ASTRETCH                 stretch 2-dim analyzer by data of 1-dim 
                          analyzer
     (ASHIFT and ASTRETCH: Source, destination and 1-dim. analyzer 
      must exist. 1-dim. analyzer must fit to the dimension of 
      operation of the source analyzer. Binsize and limits of 
      destination analyzer are free.) 
   *  Function of ASHIFT or ASTRETCH:                                   *
   *   The 2-dim. source analyzer is shifted or stretched in the        *
   *   direction of IDIM, by the amount given in the 1-dim. analyzer.   *
   *   The result is written to the 2-dim. destination analyzer.        *
   *                                                                    *
   *      IDIM_COMP                                                     *
   *          |                                      |    \             *
   *          |                                      |     \            *
   *          |        x  -->  x'                    |      \           *
   *          |         2       2                    |       \          *
   *          |                                      |        \         *
   *          |        x ------>  x'                 |         \        *
   *          |         1          1                 |          \       *
   *          |                                      |           \      *
   *          |                                      |            \     *
   *            ________________________________                        *
   *                                        IDIM                        *
   *                      2-dim. analyzer             1-dim.            *
   *                                                  analyzer          *
   *                                                                    *

  ASPACE                   list space allocated for analyzers
    If desired, the memory of SATAN analyzers is organized in 
    compressed mode. It is dynamically adapted to the required size. 
    Empty regions of analyzers above a certain amount do not consume 
    any space in memory. While the memory consumed by the analyzer 
    data is reduced, the time which several commands need is increased.
    The space actually allocated in memory can be visualized by the 
    command       
            "ASPACE"   or  "ASPACE *".
    During the analysis of list-mode data, however, those analyzers 
    being filled are converted to normal mode, and the required memory 
    increases.        
    The compressed mode can be activated by the command
            "ACOMPRESS".
    The compressed mode may be suspended by the command
            "AEXPAND".                                             
  ASUM                     list sum and moments of spectrum   
 
Handling of parameters
      
  IPAR                     create, modify, list or delete
          parameters, dec float(6) and character strings,
           1-dim. arrays are supported
          Numerical results of last command are stored in array $R 
          (see OIPAR).
          Batch status is stored in parameter $BATCH (on VMS).          
               
  IOPER                    perform arithmetic operations with parameters
          Complex arithmetic expressions are available.
          (See HELP FUNCTIONS for list of available functions and 
          constants.) Parentheses are supported.      
  CALCULATE or ?           evaluate an arithmetic expression
          Complex arithmetic expressions are available.
          (See HELP FUNCTIONS for list of available functions and 
          constants.) Parentheses are supported.      
  
Access to the numeric result of any command  
  OIPAR     copy the numeric output of the preceding command
            from protocol into the parameter $R.
                  Elements of the 2-dimensional parameter array $R 
                   can be used in the commands IOPER, AOPER etc.
                   like a dynamic parameter .
                  The first dimension of $R corresponds to the
                   number of the output line, the second counts 
                   the numeric values in the line.
                  IOPER A = $R(1,3) writes the third number of the
                   first line into the interactive parameter A.
                                Example:
                   Enter command: GDISP
                   Enter command: WLIST a
                   <I> W1: A      135      139 => SUM(0.813786) 
                   Enter command: OIPAR
                   Enter command: IOPER acounts = $R(1,3)
                   Enter command: IPAR acounts / list
                    Parameter                value           comment
                   ACOUNTS              0.813786       
  OFILE     copy the protocol output of the preceding command 
            into a file.
                   (To be used in analogy to OIPAR.)
            The command OFILE has several options to write the
             full protocol text, only the numbers of the protocol text, 
             or an explicitly given text.
                   If used like  
                     "OFILE / TEXT(Mass = &A:F5,1.,  Charge = &Z.)"
                     interactive parameters may be listed from an
                     SCOM list, also in a formatted way.
           
      
Calling a user-supplied function from the command decoder  
  Command MYFUNC:
   (up to 100 positional parameters DEC FLOAT(6) allowed)
   By the command MYFUNC, the user-supplied subroutine 
   $MYFUNC(N, RV) is called.
    Example for $MYFUNC:
        $MYFUNC: PROCEDURE(N, RV);
          DECLARE N BIN FIXED(15), 
                   /* number of positional parameters given */
                  RV(*) DEC FLOAT(6); 
                   /* values of pos. parameters */
          ...
        END $MYFUNC;
    The user-supplied routine $MYFUNC has to be linked to SATAN
    ( like or in addition to an analysis program ).       
  Command MYCOMMAND:
   (up to 100 positional parameters CHAR(*) VAR allowed)
   By the command MYCOMMAND, the user-supplied subroutine 
   $MYCOMMAND(C_COMMAND, N, C_PAR) is called.
    Example for $MYCOMMAND:
        $MYCOMMAND: PROCEDURE(C_COMMAND, N, C_PAR);
          DECLARE C_COMMAND CHAR(*) VAR, /* subcommand name */
          DECLARE N BIN FIXED(15), 
             /* number of additional positional parameters given */
                  C_PAR(*) CHAR VAR(*); 
             /* values of additional positional parameters,
                specified as ASCII character string */
          ...
        END $MYCOMMAND;
    The user-supplied routine $MYCOMMAND has to be linked to SATAN
    ( like or in addition to an analysis program ).
      
Handling of command lists
      
  SET / SEXECPATH(...)    (set one or several SEXEC paths to be 
                            scanned for the dataset to be executed.)
                            ==> GSET / PATH([MUELLER.EX1],[MUELLER.EX2])  
  SEXEC                     Execute command list (see HELP SCOM)
      
Peak search
      
  AFPEAK 
      
  Performs automatic peak search. Limits or peak positions may be
  stored in conditions, windows or display points. The counts in the
  peaks may be stored in the analyzer @PEAKS, with or without background
  correction. The procedure determines the peak width automatically,
  if FWHM is not specified.
        
  AFPEAK / LIST lists the following information:
   NO.              Peak number
   LIMITS           Limits of peak 
   TOTAL COUNTS     Sum of positive and negative counts inside limits
   POSITIVE COUNTS  Positive counts inside limits
   PEAK COUNTS      Counts above background inside limits of peak
   CENTRE           Peak position (Position of slope zero after smoothing)
   SIGNIF           Counts in peak divided by expected statistical fluctuation
      
  AFPEAK works only with analyzers.
      
 
Fit package
      
(Available for ANALYZERS and, with a few restrictions, for PSEUDO
  ANALYZERS)
      
  The following commands of the SATAN Fit-Package are available:
      
  FAREA, FDISP, FERROR, FEXP, FINIT, FIT, FLAST, FLEG, FLIKE, FLIST, 
  FMLFIT, FMY, FPAR, FPEAKS, FPOL, FPOS, FRESULT, FSTORE, FSUM, FWIDTH,
  FWIN, FXCAL
      
  See "HELP FITGEN" for details and additional background 
  information.)

      
List-mode analysis  
  Explanations of the list-mode analysis may be found by HELP LISTMODE.     
LIST-MODE ANALYSIS
      
List-mode data may be analyzed by use of a user-supplied analysis 
routine. This routine consists of two parts, written in a compact
form in one dataset. The user defines his spectra, conditions,
table of list-mode data etc. in the first part, the definition part.
The analysis for every event from the input file is performed in
the second part, the analysis part. Here the input data may be used
for calculations, for setting conditions and for accumulating spectra.
      
Example with explanations:
(In all examples given below, the first three lines are adapted to the
windows version of SATAN. The first two lines define specific features
of the PL/I compiler, the third line marks the location of the SATAN
macros.)
|%PROCESS MACRO LIMITS(EXTNAME(31)) LANGLVL(SAA2) MARGINS(1,100);
|%PROCESS RULES(NOLAXDCL);       
|%INCLUDE '\FRSTOOLS\TRI\SATAN\$MACROS.PLI';
| /* This dataset contains the macros.                                */
|
| /* General remarks for syntax and use of macros:
|       Macros may be specified with positional and keyword arguments.
|       (In "AGEN(X1) LIMITS(1,100)", "X1" is a positional argument, 
|        "1,100" is a keyword argument with the keyword "LIMITS".)
|       Positional arguments must appear in sequence,
|       Keyword arguments may appear in any order. 
|    The macros below may only be used in the analysis procedure!     */
|
|
|DEBUG;            /* switch for debug mode,                           */
|                  /* is useful for testing but reduces the speed.    */
|                  /* Without the DEBUG option, error checking is    */
|                  /* not performed (e.g. writing into analyzers      */
|                  /* which have not been created).                   */
|                  /* A new program may first be compiled with        */
|                  /* this option.                                    */
|                  /* DEBUG should not be used in the production     */
|                  /* phase.                                          */
|
|LISTPROC;         /* Begin of analysis program                        */
|
|
|    Syntax of LIST (list character strings and numerical variables)
|      Positional arguments: text, numerical variables.
|         ==> "LIST('First and second values',R1,R2);"
|                 lists the given text and the values of R1 and R2.
|
|    Syntax of EXCMD (execute a SATAN command)
|      One positional argument: command text.
|      (command text not in quotation marks!)   
|         ==> "EXCMD('HALT')" executes the command HALT.
|
|    Syntax of AGEN (create an analyzer, 1-dimensional)
|      (1-dimensional analyzer, up to 5-dim. arrays allowed)
|      1. argument: analyzer name or array of analyzer names,
|         ==> "AGEN(MUSIC)" defines one analyzer,
|         ==> "AGEN(ATAR(3))" defines an array of three analyzers,
|         ==> "AGEN(Z_RESPONSE(80:92))" defines an array of 13 
|                                         analyzers.
|         ==> "AGEN(TEST(5:9,27:37))" defines a 2-dim. array of 
|                                         analyzers. 
|      TYPE  keyword: FIXED or FLOAT (optional; default = FIXED),
|           and PROTECTED (against ACLR)   
|         ==> "AGEN(TEST) TYPE(FLOAT,PROTECTED)" defines a floating-
|                 number analyzer which is protected against ACRL.
|      LIMITS keyword: list of limits (2 values),
|      BINS  keyword: binsize (optional; default = 1),
|      NCND  keyword: number of conditions (optional; default = 0),
|      CXAXIS   keyword: description of x axis (optional; default =
|                                                             Channel),
|      CYAXIS   keyword: description of y axis (optional; default =
|                                                             Counts),
|      TITLE    keyword: title of analyzer (optional; default =
|                                                       analyzer name),
|      COMMENT  keyword: comment of analyzer (optional; default = '').
|      FCAL     keyword: calibration factor (default = 1). 
|      LINESYMBOL keyword: line and symbol (==> LTR11 , default is HT0)
|      In CXAXIS,CYAXIS,TITLE and COMMENT, & is a placeholder for the
|       element number(s) of an array of analyzers.
|
|
|    Syntax of AGEN (create an analyzer, 2-dimensional)
|      (2-dimensional analyzer, up to 5-dim. arrays allowed)
|      1. argument: analyzer name or array of analyzer names (see above),
|      TYPE  keyword: FIXED or FLOAT (optional; default = FIXED),
|                      and PROTECTED (against ACLR)  ==> TYPE(FLOAT,PROTECTED)
|      LIMITS keyword: list of limits (4 values),
|      BINS  keyword: binsizes (optional; default = 1,1),
|      NCND  keyword: number of conditions (optional; default = 0),
|      CXAXIS  keyword: description of x axis (optional; default =
|                                           Dimension 1),
|      CYAXIS  keyword: description of y axis (optional; default =
|                                           Dimension 2),
|      TITLE   keyword: title of analyzer (optional; default =
|            analyzer name),
|      COMMENT keyword: comment of analyzer (optional; default = '').
|      FCAL    keyword: calibration factors. 
|      In CXAXIS,CYAXIS,TITLE and COMMENT, & is a placeholder for the
|       element number(s) of an array of analyzers. 
|
|
|    Syntax of ACDEF (define an analyzer condition) 
|      1. argument: analyzer name,
|      2. argument: condition number,
|      ID keyword: condition id (optional; default = cond. number),
|      LIMITS keyword: list of condition limits (2 or 4 values)
|                             (optional; default = analyzer limits).
|
|     (ACDEF may be used to define the limits or the condition ID -
|       a word to characterize the condition - or both. Conditions may 
|       also be manipulated by the commands W1.., W2.., and ACDEF)
|
|
|    Syntax of AC (return the value of an analyzer condition) 
|      (for 1-dim. and 2-dim. analyzers)
|      1. argument: analyzer name,
|      2. argument: condition number.
|    $AC yields always true for conditions which are not set (= open).
|    $AC yields always false for conditions which are closed.
|
|
|    Syntax of ANAL (fill data into an analyzer, 1-dimensional)
|      1. argument: analyzer name,
|      2. argument: channel number,
|      INCR keyword: increment (optional; default = 1) or
|      VALUE keyword: set value (INCR and VALUE are exclusive).
|
|
|    Syntax of ANAL (fill data into an analyzer, 2-dimensional)
|      1. argument: analyzer name,
|      2. argument: channel number 1. dimension,
|      3. argument: channel number 2. dimension,
|      INCR keyword: increment (optional; default = 1) or
|      VALUE keyword: set value (INCR and VALUE are exclusive).
|     Analyzers used in ANAL must have been created by AGEN.
|
|
|    Syntax of AGET (get value from an analyzer, 1-dimensional)
|      1. argument: analyzer name,
|      2. argument: channel number,
|     AGET returns the content of the analyzer channel.
|    Analyzers used in AGET must have been created by AGEN.
|
|
|    Syntax of AGET (get value from an analyzer, 2-dimensional)
|      1. argument: analyzer name,
|      2. argument: channel number 1. dimension,
|      3. argument: channel number 2. dimension,
|     AGET returns the content of the analyzer channel.
|    Analyzers used in AGET must have been created by AGEN.
|
|
|    Syntax of PARDCL (declare interactive parameter) 
|      (only DEC FLOAT(6), 1-dim arrays supported)
|      1. argument: variable name,
|      INIT    keyword: value (optional; default = 0),
|      COMMENT keyword: comment (optional; default = '').
|    For arrays, the INIT and COMMENT keywords are assigned to the
|      different components in sequence. Missing values are
|      repeated from the last given value.
|    Parameters are declared in the analysis routine and may be used
|      there like a normal variable declared by
|       DECLARE "name" DEC FLOAT(6) STATIC INIT(..);
|      for reading and writing. 
|    Alternatively, a list of variables is supported.*/
|
|
| LIST('Raw analysis of MUSIC detector');
|
| DECLARE DBRHO DEC FLOAT(6);
|
| PARDCL(BRHO_NULL(3)) INIT('9.7934,9.7320,9.7308')
|                              COMMENT('central magn. rigidity');
|
| PARDCL(A0,A1,A3) INIT('-5.3,7.5,29')
|                              COMMENT('offset,slope,curvature');
|
| AGEN(MUSIC(4)) LIMITS('0,1023') BINS(2) NCND(1)
|          CXAXIS('ADC channel') CYAXIS(counts) TITLE('first music');
|
| AGEN(TOF_DBRHO) LIMITS('0,1023,-1000,1000') BINS(4,16) NCND(2)
|          CXAXIS('TOF/100 ps') CYAXIS(Delta-Brho / Brho  *  100000)
|          TITLE(Identification of masses and charge states);
|
| ANTRY; /* end of definition part, begin of data-block loop */
|
| EVENT(I_MUSIC(4),TOF,BRHO) FORMAT(SATAN) TYPE(FIXED);  
|         /* definition of list-mode event data, event loop */
|
| /*  The following data formats are supported by EVENT:
|       GOOSY   GOOSY format (see HELP GOOSYDATA for details)
|       SATAN   SATAN format
| /*  The following data types are supported by EVENT for SATAN format:
|       FIXED      (standard SATAN format, 2 byte integers)
|                     This is the default option.
|       FLOAT      (SATAN format, 4 byte reals)
|       FIXED LONG (SATAN format, 4 byte integers)
|       FLOAT LONG (SATAN format, 8 byte reals)
|       ASCII,  (simple ASCII format, data of one event per line;
|                   data may be reals or integers, 
|                   divided by at least one blank)
|                Lines in the input dataset beginning with "*" are ignored.
|  */
|   DO I = 1 TO 4;
|     ANAL(MUSIC(I),I_MUSIC(I));
|   END; 
|
|   DBRHO = FLOAT(BRHO - BRHO_NULL(1),6) * 100000.E0;
|   IF AC(MUSIC(1),1) THEN
|         ANAL(TOF_DBRHO,TOF,DBRHO);
|
| /* Hints to handle events with variable length in SATAN format:       */
| /* 1. Supply the maximum number of parameters for the EVENT macro     */
| /*      which may ever appear.                                        */
| /* 2. Assign the actual number of parameters to the variable $N_EVT   */
| /*      just before the macro ENDEVT.                                */
| 
| ENDEVT; /* end of event loop */
| $CONDITION_CHECK();  /* check on declared but unused conditions */
| ENDANL; /* end of data-block loop and of analysis routine */
      
 
The same thing without comments:
      
|%PROCESS MACRO LIMITS(EXTNAME(31)) LANGLVL(SAA2) MARGINS(1,100);
|%PROCESS RULES(NOLAXDCL);
|%INCLUDE '\FRSTOOLS\TRI\SATAN\$MACROS.PLI';
|DEBUG; 
|
|LISTPROC;
|
| LIST('Raw analysis of MUSIC detector');
|
| DECLARE DBRHO DEC FLOAT(7);
|
| PARDCL(BRHO_NULL(3)) INIT('9.7934,9.7320,9.7308')
|                              COMMENT('central magn. rigidity');
|
| AGEN(MUSIC(4)) LIMITS(0,1023) BINS(2) NCND(1)
|   CXAXIS('ADC channel') CYAXIS('counts') TITLE('first music');
|
| AGEN(TOF_DBRHO) LIMITS('0,1023,-1000,1000') BINS(4,16) NCND(2)
|   CXAXIS('TOF/100 ps') CYAXIS('Delta-Brho / Brho  *  100000')
|   TITLE('Identification of masses and charge states');
|
| ANTRY;
|
| EVENT(I_MUSIC(4),TOF,BRHO) FORMAT(SATAN) TYPE(FIXED);
|
|   DO I = 1 TO 4;
|     ANAL(MUSIC(I),I_MUSIC(I));
|   END; 
|
|   DBRHO = FLOAT(BRHO - BRHO_NULL(1),6) * 100000.E0;
|   IF AC(MUSIC(1),1) THEN
|         ANAL(TOF_DBRHO,TOF,DBRHO);
|
| ENDEVT;
| $CONDITION_CHECK(); 
| ENDANL;

      
MONTE-CARLO simulations
      
Another version of the analysis program may be used for
MONTE-CARLO simulations
      
Example for a MONTE-CARLO analysis program:
      
|%PROCESS MACRO LIMITS(EXTNAME(31)) LANGLVL(SAA2) MARGINS(1,100);
|%PROCESS RULES(NOLAXDCL);
| %INCLUDE '\FRSTOOLS\TRI\SATAN\$MACROS.PLI';
| LISTPROC;
|
|     DECLARE I BIN FIXED(31) INIT(0);
|     DECLARE ...
|     PARDCL(...
|     AGEN(...
|
|   START;  /* entry for commands START and CONTINUE */
|
|   LOOP;   /* begin of event loop */
|
|     ...      /* simulation calculation */
|     ANAL(...
|     I = I + 1;
|     IF MOD(I,10000) = 0 THEN EXCMD('LHALT');
|
|   NEXT;   /* end of event loop */
|
| ENDANL;
      
 
The program starts execution at START by the command LSTART.
The extension of the loop can be specified by the LOOP
macro (see HELP MACROS) and by the command LSTART (see HELP LSTART).
      
The loop from the macro LOOP to the macro NEXT can be stopped by 
pressing CTRL/C (VMS), or by pressing the BREAK button of the 
SATAN interface window, or by executing EXCMD('LHALT') in the program. 
In the example, the program stops after 10000 events. When it is 
restarted with LCONTINUE, it is stopped again after another 10000 
events.
                        
                  
MODEL CALCULATION  
A model calculation without a MONTE-CARLO event loop looks like the
following example: 
      
|%PROCESS MACRO LIMITS(EXTNAME(31)) LANGLVL(SAA2) MARGINS(1,100);
|%PROCESS RULES(NOLAXDCL);
| %INCLUDE '\FRSTOOLS\TRI\SATAN\$MACROS.PLI';
| LISTPROC;
|
|     DECLARE I BIN FIXED(31) INIT(0);
|     DECLARE ...
|     PARDCL(...
|     AGEN(...
|
|   START;  /* entry for command START */
|
|     ...      /* simulation calculation */
|
|     ANAL(...
|
| ENDANL;      
 
Generating or compressing list-mode data  
Writing list-mode data by an analysis program is supported. This 
feature may be used for creating list-mode data (e.g. from a 
Monte-Carlo simulation) or for compressing data by omitting part of 
the event parameters or by writing pre-analyzed data.      
First you must write an analysis program. Either it reads the input 
list-mode data from file and defines the new list-mode data to be 
written or it generates itself the list-mode data to be written.
Here an example for an analysis program for compressing existing 
list-mode data:
(A new file is written with 3 event parameters taken from 120 initial
event parameters.)      
|%PROCESS MACRO LIMITS(EXTNAME(31)) LANGLVL(SAA2) MARGINS(1,100);
|%PROCESS RULES(NOLAXDCL);
| %INCLUDE '\FRSTOOLS\TRI\SATAN\$MACROS.PLI';
| LISTPROC;
|
|     DECLARE N_EVT BIN FIXED(15);
|     DECLARE IV_EVT (3) BIN FIXED(15);
|     DECLARE I_RC BIN FIXED(15);
|
|   ANTRY;  
|
|   EVENT(I_EVT_IN(120));   
|
|   IV_EVT(1) = $FIXED(I_EVT_IN(13),15);
|   IV_EVT(2) = $FIXED(I_EVT_IN(27),15);
|   IV_EVT(3) = $FIXED(I_EVT_IN(104),15);
|   N_EVT = 3;
|   
|   LOUT DATA(IV_EVT) N(N_EVT);
|
|   ENDEVT; 
|
| ENDANL;      
LOUT can handle data arrays of BIN FIXED(15), BIN FIXED(31),
DEC FLOAT(6), and DEC FLOAT(15) values.      
The use of the $FIXED function is recommended for BIN FIXED(15)
data because it prevents the FIXEDOVERFLOW condition to occur 
in case the input values exceed the range of the BIN FIXED(15) 
variables.      
Here an example of DEC FLOAT(6) values:      
|%PROCESS MACRO LIMITS(EXTNAME(31)) LANGLVL(SAA2) MARGINS(1,100);
|%PROCESS RULES(NOLAXDCL);
| %INCLUDE '\FRSTOOLS\TRI\SATAN\$MACROS.PLI';
| LISTPROC;
|
|     DECLARE N_EVT BIN FIXED(15);
|     DECLARE RV_EVT (3) DEC FLOAT(6);
|     DECLARE I_RC BIN FIXED(15);
|
|   ANTRY;  
|
|   EVENT(I_EVT_IN(120));   
|
|   RV_EVT(1) = FLOAT(I_EVT_IN(13),6) / FLOAT(I_EVT_IN(15),6); 
|   RV_EVT(2) = FLOAT(I_EVT_IN(27),6) * 1.E-5;
|   RV_EVT(3) = FLOAT(I_EVT_IN(104),6);
|   N_EVT = 3;
|   
|   LOUT DATA(RV_EVT) N(N_EVT);
|
|   ENDEVT; 
|
| ENDANL;      
For reading these list-mode data with another analysis program, 
the appropriate data-type option (FIXED, FIXED LONG, FLOAT or
FLOAT LONG) must be specified in the EVENT macro, otherwise FIXED is assumed.                                     
                                          
The analysis program must be linked to SATAN. Then SATAN is started.
For writing modified data from existing list-mode data, the new data 
file is written by applying the following commands in SATAN:      
   LOUTPUT / DSN(output dataset name)
   LINPUT / DSN(input dataset name)      
If the list-mode data are generated in the user-supplied program (e.g. 
see "MONTE-CARLO simulations" above), the following commands have to be 
entered:      
   LOUTPUT / DSN(output dataset name)
   LSTART      
Another LOUTPUT command with a new dataset name will close the output 
dataset and open the new one. The last output dataset is closed when 
you exit SATAN.
      
Preparing an executable program
=============================
      
The analysis routine, if written in analogy to the above example, may 
be compiled without any further options by the normal PLI compiler.          
On Microsoft WINDOWS:  
Compile the program(s) with the command "PLI module".
Link the program with "SLINK module1.obj [module2.obj module3.obj ...] "
Run the program with "module1".
("module" stands for the name of your program(s).)
           
      
Subroutines
      
In addition to the analysis routine, the user may supply the following 
routines:
(These procedures do not have any parameters.)
      
   routines                     called with
-------------------------------------------------------------
   $MYINP                       command INPUT
   $MYGO                        start of reading list-mode data
   $MYHALT                      halt of reading list-mode data
   $MYEXIT                      command EXIT
      
These routines have to be added to the LINK list just behind the
analysis routine.
      
 
The user may apply the following procedures: 
(See also HELP MACROS for more detailed information)
(The following abbreviations are used:
  CVx: CHAR(x) VAR, B1A: BIT(1) ALIGNED, Ixx: BIN FIXED(xx), Rxx DEC FLOAT(xx))  
   routines                function
-------------------------------------------------------------
   $PRTCL(CV,I15)         write to screen and to protocol (I15=1)
   $PROMPT(CV,any)        prompt a variable
   $PROMPTO(CV,any)       propose and prompt a variable
   GPEDIT(R15,I15) RETURNS(CV256)   transform a DEC FLOAT(15) number
                            to a character string with given precision
   $2FIX16FLOL(I15,I15) RETURNS(R15)  converts two unsigned 16bit 
                                      numbers (BIN FIXED(15)) 
                                      (e.g. from 32 bit counter) 
                                      to one DEC FLOAT(15) number
                            ==> RESULT = $2FIX16FLOL(I_LOW,I_HIGH);
   $2FIXL16FLOL(I31,I31) RETURNS(R15) converts two unsigned 16bit 
                                      numbers
   $2FIXL24FLOL(I31,I31) RETURNS(R15) converts two unsigned 24bit 
                                      numbers
   $FIXED(value,precision) RETURNS(Ixx)
                                    transform a value of a variable 
                                    into BIN FIXED format with 
                                    indicated precision.
                                    (Precision values 7, 15, 31 are
                                     supported. Protected against fixed 
                                     overflow, values are limited 
                                     inside permitted range.)
   $NLBL(CV) RETURNS(CV256)          remove leading blanks
   $NTBL(CV) RETURNS(CV256)          remove trailing blanks
   $NOBL(CV) RETURNS(CV256)          remove all blanks
   PRN RETURNS(R6)                   random generator (0 .. 1)
   PGAUSS(R6,R6) RETURNS(R6)        random generator (Gaussian 
                                     distribution)
                            ==> R1 = PGAUSS(R_MEAN,R_SIGMA)
      
    and several other routines.
      
The procedures beginning with a $ sign as well as PRN and PGAUSS
are predeclared in the analysis routine.        
      

      
Special macros for Monte-Carlo simulations:  
START;
   (or $START)
   entry for START command      
LOOP;          /* or LOOP(N); for loop over N events */
   (or $LOOP)
   event loop       
R6 = PRN;                         [RETURNS(DEC FLOAT(6))]
   uniform random generator (between 0 and 1)      
R6 = PGAUSS(R6_mean,R6_sigma);   [RETURNS(DEC FLOAT(6))]
   Gaussian random generator      
NEXT;
   (or $NEXT)
   end of event loop
      
Additional procedures:  
R6 = $IPARVAL(CV_name);
   get value of the dynamic parameter CV (Normally not necessary in
    the analysis procedure, there ,the dynamic parameter is 
    directly accessible as a variable.)
   Declaration: DCL $IPARVAL ENTRY(CHAR(*) VAR) RETURNS(DEC FLOAT(6));  
CALL $PRTCL(CV,I15);
   list character string 
         on protocol and screen      (I15 = 1)
         on screen only              (I15 = 11)
         on screen without linefeed (I15 = 12)
         on protocol only            (I15 = 0)
   Declaration: DCL $PRTCL ENTRY(CHAR(*) VAR, BIN FIXED(15));       
CALL $PROMPT(CV,any);        
   prompt a variable        
CALL $PROMPTO(CV,any);
   propose and prompt a variable   
   any may be  DEC FLOAT(6),
               DEC FLOAT(15),
               BIN FIXED(15),
               BIN FIXED(31),
               (*) DEC FLOAT(6),
               (*) DEC FLOAT(15),
               (*) BIN FIXED(15),
               (*) BIN FIXED(31),
               BIT(1) ALIGNED.
   Declaration: %INCLUDE \FRSTOOLS\TRI\SATAN\$PROMPT.MAC;  
CV256 = GEDIT(R15,Cformat)
   transform a DEC FLOAT(15) number into a character string with a 
   format defined by Cformat 
   ==> CV256 = GEDIT(R15,'F9,3'); gives 9 digits with 3 digits 
   behind the decimal point.
   Declaration: DCL GPEDIT ENTRY(DEC FLOAT(15), CHAR(*) VAR) 
                     RETURNS(CHAR(256) VAR);      
CV256 = GPEDIT(R15,I15) 
   transform a DEC FLOAT(15) number into a character string with given 
   precision. The length of the character string is variable. 
   Declaration: DCL GPEDIT ENTRY(DEC FLOAT(15), BIN FIXED(15)) 
                     RETURNS(CHAR(256) VAR);      
CV256 = GPEDFL(R15,I15)
   transform a DEC FLOAT(15) number into a character string with 
   minimum length I15.
   Declaration: DCL GPEDFL ENTRY(DEC FLOAT(15), BIN FIXED(15)) 
                     RETURNS(CHAR(256) VAR);      
CALL MCMDDEC(C_COMMAND,I15);
   execute a command
   Declaration: DCL MCMDDEC(CHAR(*) VAR, BIN FIXED(15));       
-----------------------------------------------
See "HELP GOOSYDATA" for macros needed for reading GOOSY data.