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).)
Note that SATAN provides a default analysis program. When no user-defined
analysis routine is provided, the default analysis routine for reading
a list-mode-data file with up to 256 parameters is pre-defined.
See “Help DefaultAnalysis”.
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. | 