Spectrum Analysis

X-window based Analysis Package for Nuclear Spectroscopy Data.


Gerfried Kumbartzki

Where to find XSA

The XSA distribution (Download) is available as a compressed tar archive. The compilation of XSA requires the Motif 1.2 toolkit.
Under LINUX or Mac OS X openmotif-2.1.30 or higher works fine.


XSA is a program to manipulate and analyze 1-dim. histogram data sets, called Spectra.
2dim. data sets, Matrixes, can be read, and a number of operations may be performed (e.g. making cuts, projections).

XSA has two major communication modes:
Command Window  command or text input mode
Graphics Window    cross-hair or cursor mode (GUI)

The user can move freely between the two windows. Clicking the left mouse button in the corresponding window switches input focus. In the command window command lines can be recalled, edited and re-issued. In the graphics window key-press and mouse-button events are used to manipulate the picture and advance the program.

Output is provided in an one-line Textwidget below the graphics widget and in the terminal window from which XSA was launched.
XSA creates log-files, like "saMMDDYY_time.dat","results.dat" (appends to existing logfile), to record useful information and results.

Data (Spectra)

Data are read from data files and stored in a contiguous data array in memory as real integers.
A XSA-file requires a special File header. For compatibility, Radware (.spe) and ASCII-array (.asc) data files are accepted.

XSA can be called to use shared memory for its data space ("xsa -s"). The shared memory segment has to be initialized with the program shm_init (which is part of the distribution). In data acquisition applications the shared memory segment can be filled by a separate histogram process and viewed, analyzed and saved with xsa.

      Total data space allocated   440k
      Work area                     16k
These sizes are limited to comply with default shared memory sizes. Data can be placed anywhere in the data space. A total of 440 spectra can be in memory at one time. (see read).

Data/Spectra are referred to (see display) by their histogram_id (try ls "listing").
There are two id's; the first id uses the placement in data space starting with id 1 for the first spectrum or the histogram_id which is inherited from the data file. Either id can be used to reference the spectra (see Options menu).

The work area has the default id 0.

Generally, whole spectra are addressed and manipulated, but data can be viewed and processed in absolute data space by using the proper array addresses. For convenience kilo numbers (chunks of 1024 data words) can be used. When appropriate, a number appended with a k or K will be multiplied by 1024 (eg. 1k -> 1024).
Note: when accessing the data array as a whole, keep in mind that the zero point is the start point (array offset) of the current spectrum. Therefore, only a call to the first spectrum (ds 1) selects as zero point the begin of the data array.


Under the FILE menu is the Sa Command Window (command widget). All command widget properties apply, like command history list. Especially, any command can be repeated by double clicking the command. Command lines consist of a code word and input in form of text words and/or numbers.
The number of input entries is important as it determines in many cases the action taken (for a typical example see addc).

A command terminated without input is executed with default or former input parameters.
Not all parameters have to be provided every time.

Most commands act on whole spectra.
In general, data (spectra) should be changed, only in the work area.
One or more spectra are copied into the work area using the select command.

Tasks List

Add/sub (adding or subtracting spectra)

Spectra of same length can be added or subtracted. The result is found in the work area. The command adds to or subtracts the data from the content in the work area.
A typical command sequence would be

   sel  id      put spectrum id in work area
   add  idx     add spectrum idx to the first and display
                the result in the work area.
The add command can take a list of spectra id's


	sel 1
	add 2 3 4 will add the three spectra to the content (spectrum 1) in
                  work space.
        + 3       will add spectrum 3 to work space data.
        sub 5 - 8 will subtract spectra 5 6 7 and 8 form content in
                  work space
The cmd "+" is synonym with "add", similar "-" can be used instead of "sub".
If the work area is empty, the sel command can be skipped when adding spectra.

Add constant to data

A constant will be added to the selected data.
    addc constant       to currently displayed spectrum.

    addc id constant    addc constant to spectrum with id

Command_file Mode

Most useful, command files can be executed within XSA.
A command file is a list of input lines as typed in the command widget.
For instance: Edit a cmd-file (a collection of valid commands) like
   r file1 0         ;read and store file1 at beginning of data array
   r file2 4k        ;read and store file2 starting at address 4096
   add 1 2           ;add file2 to file1 (result in work area)
   w file3           ;write sum spectrum to file3
and save the list as a file e.g."read2"

Execute the file by calling

   run read2
Any filename starting with the letters mk (make) will be run as command file without the "run" command. Such a mkfile command is searched for first in the current directory and then in the directory pointed to by the environment variable XSACMD. If the mkfile has a pathname attached, like ../mkread, the command run ../mkread has to be used. In addition, a mkfile within a cmd-file has to be used with the run cmd.
A limited argument substitution $1 to $5, like in a shell cmd, can be used.


Assume the command file "mkread" is:

     open $1par.his
     rs $2
It can be executed as
     mkread sma 0  or
     mkread smb 3
First, if a file smapar.his exists and contains a spectrum 0 it will be read, next, the file smbpar.his will be opened and spectrum 3 will be read and stored after the first spectrum.


Energy Calibration

The calibration is a linear fit between two energy values. The energy values have to be typed in, the corresponding channels can be taken from the display ('z' or right mouse btn for channel or 3 point centroid). It is important to do the two markings without leaving the display mode. The energies and positions have to be in increasing order. Each spectrum may have its own calibration.
First display the spectrum (ds) then calibrate.
The actual data are unchanged, only the horizontal scale is relabeled.

The number of input tokens determines the action:

  cal 1.Energy 2.Energy
		Type the energies and get the
		channel information from the display.

After typing the two energy values in the command line, go to the Graphics Window, locate and mark with the right mouse button the first calibration point, then do the same for the second point. The calibration will be shown in the terminal window.

  cal 1.Energy 2.Energy 1.Channel 2.Channel
		provides all information for a calibration
		of the current id.

  cal spectrum_id slope zero_offset
		a known calibration is provided.
		If id is all, all spectra in memory
		get the same calibration.

  cal [CR]      resets calibration to channel numbers,
                which is the default "calibration".
  cal all       resets calibration for all spectra.

  cal filename	calibration stored in a file is read in.

  mcal 2 - 10 slope zero_offset
                multiple id's for the same calibration.

  wcal filename	The calibration can be stored in a file.
		New calibrations are appended to an
		existing file.

  rcal filename A wcal file can be read back (same as 'cal filename').

  cpcal id      After displaying or selecting a spectrum
		the calibration of id is copied to the current spectrum

  esc		(e-scale)
                toggles between "ENERGY" and "CHANNEL NUMBER"
		scale in the display (see also Options menu).

Copy Spectra into work space

The command select puts data from the data array into the work area:
  sel id
	sel 2      duplicate spectrum 2 in work area.
	sel 1 3    put 1 and 3 in this order in work area.

Display Spectra

Viewing data is started using one of the following display commands. Once a picture is drawn the viewing field can be modified with single key strokes and mouse buttons actions.
  ds id [-ymax]	Display spectrum with identification id.
		up to 8 spectra can be displayed
		simultaneously on the screen.
		The default id is the position in the
		absolute data space 1,2,3,....
		When appropriate spectra can be selected by
		their intrinsic id (provided by the data file).
		setid toggles between both modes.
		If the last entry is < 0 it is taken as maximum
		of the y-scale
  ds  1 2 3 4	for instance, will display the first 4 spectra.
  ds  1 - 4     has the same effect (spaces are important).
        	The order can be chosen arbitrarily,
		eg. 1 3 8 5.
		Again, if the last number is negative,
		it will be used as YMAX for a fixed scale
		for all displayed spectra (eg. ds 1 2 -500).
  ds  2 -500    show spectrum 2 and set ymax to 500.

  do id		plots data over old picture, use scale of first.
  do id col	specify in addition color of overlaid spectrum.
  do 2 red -100 a optional third input will be taken as YMAX
		for the overlaid data.
  do 2 green -1 a '-1' as last input invokes auto scaling for the overlaid
  do 2 black 0  a 'zero' as last input expects a button click in the display.
                The overlay spectrum will be drawn with the data point at
                the cursor position.

  ov id         similar to 'do id', but several spectra can be overlaid at once.
  ov 2 4 5      overlays on the current display spectra 2 4 and 5.
  ov 1 - 16     put all 16 spectra with different colors on top of each others

Select a display range.

  dsr 100 512	The display field starts
		at channel 100 and has a length of 512
		until reset using
  dsr[CR]	without parameter.

  dsr 512	If only one input parameter is provided
		it defaults to a new display length.

Define new first channel and display length.

  d fch lch	first channel last channel
		If last channel is less than first channel,
		last ch is taken as the display length.
		First and last channel are relative to the
		last displayed spectrum.
  d 0 1k	displays the first K of current spectrum

  d[CR]		repeats former setting (repaints display).

  d id          displays the same region for spectrum with new id

If, for instance, in peak mode the same peak in several spectra should be analyzed, 'd x' shows the same peak in spectrum with the new id 'x'.

Single Stroke Commands in Graphics Window

After drawing the picture clicking in the graphics window (left mouse button) switches input focus to that window. The X11 can be setup for "focus follows mouse".
On a Mac under X11 go to Preferences → Windows...

Mouse button clicks and single characters from the keyboard can be used to manipulate and analyze the data.

Use of mouse buttons:

  Key commands list in alphabetical order - no CR needed

Automatic peak search, peaks are marked (Max 100),
if spectrum calibrated, energies are shown.
Calculate and display background.
b has to be followed by a number between 0 and 5. This number is the order of the polynomial for the background fit, e.g. b1, bb uses the last order again, b- (bminus) no background applied.
The background is fitted to the data in a window marked 0 to 1 on the left side and 4 to 5 on the right side of the peak. Both background windows can be on one side of the peak (more information in topic peak)
c Clear all marker
d redisplay (clean)
e Expand spectrum between two successive 'e'
f Fit up to 4 Gaussian to selected data (see peak)
g Grab/UN-grab nearest marked peak for integration or fit. If no peak is marked, select around cursor
h Display selected region - 1024
i integrate peak area
j Display selected region + 1024
k Kill last marker
l Toggle between lin and log display
m Mark at cursor position (Same as middle mouse button press)
n Next - display higher data region. In peak mode select next peak
o After do redraw overlaid spectrum at cursor position,allows to match both data sets
p Previous - reverses n
q Replace data between marks by next number typed (0-9)
r Reset expand (remembers 10 levels)
s Sum (integrate) peak content between markers 2 and 3 subtract background in peak mode (same as i)
t Type list of markers shown in display window (channel number, energy and data)
u Update, redo peak, especially useful in ud
v import marks of former peak, similar to 'pm', V - repeats marks from p 0
x Same as 'e'
y Set new y-scale to vertical cross-hair cursor
Set channel number or energy (if provided) at vertical cross-hair position if above the data. A 3 point centroid is calculated if the cursor is at the highest of three channels (Same right mouse button press)
; Toggle between Channel and E-scale display
esc Toggle between Channel and E-scale display same as ';'
, Set successive marks equally spaced (distance between marks 0 and 1)
" Mark the next window with same width as previous window, eg. m2,m3,m4 " m5 will be at m4+(m3-m2)
. Identify channel number and content (Same left button press)
= Display sum of channels between enclosing markers
+ Print sums between all markers
0-9 Immediate shift of that marker to new cursor position
space Enlarge window in progressive steps
< "move" histogram in window to left
> "move" histogram in window to right

Gain match Spectra

Histograms can be shifted and gain adjusted.
A gain match factor and/or shift factor have to be provided The default is: gain = 1.0 and shift = 0.0 The factors can be set using gmf.
gmf without input resets the shift and gain match factor.


   gmf 1.007 -8.2  sets the gain match factors to the given values
   gmf -5.3 (one input item only) is taken as shift factor.
   gmf 600.0 1600.0 605.0 1640.0
                will calculate gain match factors to
                match channel 605 to 600 and 1640 to 1600.

   gmf 0.5 0.0	the new spectrum will be half the length
   gm id     does the matching. The result is in the work space.
Typically, the last displayed spectrum will be adjusted. If an id is provided, that spectrum will be used.
Similar functionality is provided with the shift and rebin commands.


    shift 1.23   shifts the current spectrum by 1.23 channels to the right
                 WARNING: the result is in the current spectrum not in the work area.
                 Always the original data are shifted.
                 Shifts can be negative (to the left).
    rebin 1024   the current spectrum will be re-binned to 1024 channels.
                 the results is always in the work area.
    rebin 1024 3 spectrum with id 3 will be re-binned to 1024 and left in
                 work area.

For gain matching a set of detectors, like Clover detector segments, the gain match information (gain match factors) can be derived within XSA and written out into a file (date_time.gmf).
First, the peak information for the new position (two energies) is provided with the cmd

    pp e1 e2
this initiates a mode where the next two peak positions in the current spectrum should be selected (peak centroids - click right mouse button). Display next spectrum and select next two peaks and so on.

After for all detectors the reference positions were determined

    pp out  (0 is equivalent to out)
is used to write the currently stored information out and the pp mode is terminated. Any selection can be repeated by using
    pp nr
where nr is 1 - 16 (16 detectors max). If nr is omitted the current display id is used. Like
    ds 1
or clicking in the spectra listing.


Multiplication/Division of Spectra

Calculate square or ratio of spectra. Select on spectrum, sel id, and
    mul id	Spectrum in work area is multiplied by spectrum with id
    div id	Spectrum in work area is divided by spectrum with id
		The result is in work area.

Multiply data by Constant

Multiply data with a floating point number. To divide use fractional factors. Interface like in addc or cut
   mulf factor	multiplies current spectrum

   mulf id factor
		multiplies data in spectrum id.


   sel 1        put spectrum 1 in work area
   mulf 0.75    multiply each channel by 0.75

   mulf 2 1.5   multiply each channel of spectrum 2 by 1.5

Mark Position - Move Marker

A position in a spectrum can be 'marked' from the command window.
    m number	where number is the channel number or
		energy if the spectrum is calibrated.
One or a group of markers can be moved to a new position. Type
    mm # [#] [#]

    mm 12 14
then click with the left mouse Button at the new position for the first marker.

List Spectra

Pull down File menu and choose listing or type
    ls		all spectra in core are shown in a list widget and terminal,
		index,id,name,begin in array,[length,calibration data]
Spectra can be called by index or id (toggle setid) If identical id's exist in separate spectra, the index has to be used.
    setid	toggles between id and index. 'id' is default (see Options menu).

Print Data

Data of the selected spectrum are written to the terminal if no filename is provided. A filename is given like for redirected output in the shell.
    pd first_channel last_channel
    pd first_channel last_channel > filename
    pd 100 150	the data from channel 100 and including
		150 will be printed out.
The data can be exported as xmgrace data file for plotting.
    pdg 0 1k > spec2.dat

Postscript Pictures


produces a postscript file 'sagraph.ps' containing the current picture.
ps works similar to the ds command.  ps[CR] takes effectively the screen picture.
Text enclosed in " " is taken as title of the graph.

   ps 1 2 "Detector 3"
Spectra 1 and 2 with a title 'Detector 3' are written into sagraph.ps
   ps 1 "Title" > newname.ps (writes to the named output file)

A single spectrum is shown in Landscape format.
If the spectrum contains marker, all marks set in the display window or region will be converted into channel numbers or energies (if a calibration present) and written into the plot. If appropriate, a 3 channel centroid, using the adjacent channels, will be calculated.

   lps id [-ymax]    sends the ps file directly to the default printer.
                     Equivalent: Print of file menu which 'copies' the screen.
   pso id1 id2 [id3] Graphs are overlaid (in colors)
   pso               the overlay picture uses the current screen layout
                     preserving y-scales
   pso 2 5 [-ymax]   

   ps1               plots spectra in 1 column (PORTRAIT)
                     1-8 spectra fit on one page.
   ps1 2 - 5 > nn.ps spectra 2 3 4 5 are written to postscript file 'nn.ps'

   ps2 1 - 16        does the same in 2 columns 
                     Up to 16 spectra fit on one page

The title can use super or sub scripts. Subscripts start with "_" and and end with "^" and vice versa. So, ^152_Eu becomes 152Eu.


   ps 1 2 "^152_Eu"   The title needs the double quotes

Peak Integration or Peak(s) Fitting

A major part of the data analysis is the determination of the area in a peak.

Single, well separated lines (peaks) can be integrated (counts in the peak are simply added up) or the peak can be "fitted" to a Gaussian shape and its area taken. Multiple, unresolved lines can so be fitted.
Special attention should be paid to the background subtraction. First a region on the left side of the peak representing background is marked (m0 and m1) then the peak region (m2 and m3) followed by a second background region (m4 and m5) are marked. The program was written with the visual inspection of each peak integration in mind. Adjust individual marker to get the best result.
Since not all peaks are of interest, begin by first selecting (mark) all the peaks to be analyzed.
In command mode peaks are called by their marker number.

    p peak_no	peak number
      width	optional width of display window
		Default is 64 channels left and right of peak.

    pm peak_no  imports all peak marks from the specified peak
    p 0 [110]	select peak zero. The optional [#]
		replaces the width parameter.
    p [CR]	repeat last peak
    pm 0        make peak marks from peak zero the current markers.
In the graphics window the peak integration can be handled with single key strokes and the mouse.
A marked peak can also be selected by moving the cursor close to the peak and typing g for grab, minimizing the back and forth between command and graphics window.

The peak and a window around the peak will be displayed. Set markers for background region left (0 to 1) peak region (2 to 3) and background region right (4 to 5).

Fit background polynomial b. If no bkgd is needed, simply do not select the order of the bkgd polynomial or reset it with b-. If no background subtraction is intended only two marks (0 and 1) are sufficient.

A simple summation is started with s (sum) or i (integrate).

For a Gaussian fit the center of the peak or peaks (max 4) has(ve) to be marked (marker 6 to 10) before f (fit) is started. Even if no bkgd will be used all marks have to be set.

The results are written to the screen and to the file sa.dat and also into the file results.dat, which contains a compressed peak analysis summary of your session. All markers and the order of the background polynomial are stored for further use. All display mode commands are enabled. After a fit or peak area summation of the selected peak typing g returns the picture to the full screen, n/p selects the next/previous peak.

Sometimes, it is desirable to sum many peaks automatically. Using the so called 'flat upper limit' method a background can be determined for the whole spectrum and then subtracted.

    ful id
A 'background free' spectrum is generated in the work area and the background spectrum is left in the adjacent work area for viewing and error calculation of peak sums (addr: w+len).


    ds 1         that's your spectrum
    ful 1        does the background calculation
    ds w         show the data without bkgd (see sum)
    ds 1         shows data
    do w+2k red  overlays the bkgd curve (if a spectrum has length of 2k)

Setting marker pairs for peak regions and issuing the command sum produces a list of peak sums (center of gravity, peaks sum, peaks sum error).


    sum 2        sum between all marker pairs in spectrum 2,
                 errors are sqrt of content.
    sum 3 1      sum in spectrum 3, take bkgd  and errors from spectrum 1
    sum 3 w s    sum in spectrum 3 (no bkgd subtracted), 
                 take errors from spectrum in work area using 
                 sqrt of these sums as error only.
                 beside s, n (no bkgd), b (bkgd), similar ps, pn and pb.
                 p signals that marker pairs are set in peak mode.

Read Histogram Data

Data can be input in various ways:
read whole file at once
ra read next spectrum and append in data array
rs read one "spectrum" at a time
rc read column(s) of matrix file
rr read row(s) of matrix file

Internally, all data are stored and used as real (float) independent of their file format.
Lets fname be a data file name.
If fname has the extension .asc or .spe the corresponding file format is assumed, else a xsa-file format is expected.

    r fname     file name of spectrum, optional
      K no      K no of start address in memory.
		Read_in should start only on full k boundaries.

    r fname 2k	the named file is read and stored in this case from address
		2048 on-wards the length is taken from file header.
		If the K no is omitted, the new data are stored
		at the beginning of the data array overwriting old data.

    ra fname    the next data are appended in the data array.

    rs fname
		file name of spectrum
       Spec no	spectrum to be read from file
       Address	start address for data in memory array

    rs name 1 0
		spectrum with id 1 of named file is read and stored
		beginning at addr 0. 
In subsequent reads from the same file only the spectrum number and optional the K number are required (rs 2 0). Without the K number subsequent spectra are appended in the array.


    r xyz.his   read spectrum set (can be up to 124 spectra), start at zero
    ra xb.his   append next data in memory
    open xz.his open file useful for reading parts of set
    file xz.his synonym for open
    rs 0 0      read spectrum 0 of open file
    rs xz.his 0 0  same as above
    rs xb.his 0 read spectrum 0 from new file and append in data array

2-dim. Files

    rr File_name matrix name
    row		 starting row
    rows	 number of rows
    address	 start address for data

This creates a cut of the matrix and stores the result as spectrum.

Similar input is used for reading columns. The short input form requires no File_name. If another file name is needed the long form has to be used or a file can be opened using the command

      file  name	open file for subsequent reading
      open  name        is synonymous.
The cd command can be used to set a path to a different directory. cd without input resets to the default directory. Likewise pwd tells where data are read from. A File menu entry Open... brings up a file selection box from which a read (reads the whole file into the next free data space) or open (opens only the file) can be selected.

File Header

The first 1024 bytes of a "SA data" file constitute a Header Block with the following structure:
  struct filehead {         /* File Header Block */
      char name[16];        /* Character line: "his/.." */
      int  nrun;            /* Run number */
      int  dtype;           /* Data Type: 0 long; 1 short unsigned; 2 real*/
      int  len;             /* Total Number of Channels */
      int  maxid;           /* Max Number of Spectra */
      struct {	      
          int id;           /* spectrum id */
          int offs;         /* begin of spectrum in file */
      } sinfo[124];         /* id and offset of each spectrum */
A data file always starts with the word 'his/' or 'data/*'[phased out], the next characters can be anything followed by '\0'.
If flhd.dtype >= 3 a matrix format is assumed.
	flhd.maxid         = 1;
	flhd.sinfo[0].id   = row_length;
	flhd.sinfo[0].offs = column_length;
flhd.len is the total number of data words (excluding the header). A file can contain up to 124 spectra (sinfo) each can have an unique identification number (flhd.sinfo[i].id) and has to have a start point. By definition flhd.sinfo[0].offs = 0;

Read Marks back

All marks (general and peak mode) are read from a file with the extension .mks. Such a file is created with the commands wmarks or wm.
The filename extension .mks is appended automatically.
    rmarks filename of marker file.
    rm     (for short)

Read Variable

Some variables, like thet1, thet2 and thet3, angles used for the anisotropy and slope calculation, can be changed in the GUI, but also "dynamically" read in within a cmd-file. The cmd format is
    rv name value
    rv thet3 70.0
    rv thet1 50.0
    rv qs 0.97 0.9
    rv slope value
List of variables
thet1 angle 1
thet2 angle 2
thet3 angle 3
qs q2   q4
slope slope   δslope
ud1 1 or 0
ud2 1 or 0
eff value   δvalue
The so provided slope takes preference until canceled with
    rv slope 0
The zero value can also be given in the Anisotropy window.

Reset Marker Array

    reset[CR]	all markers including the background
		markers are cleared.

Set output File Head

Data written into a file from the work area can be structured as several spectra (standard data format).
    sflhd num	   select number of spectra
The number of channels per spectrum is calculated from the total length and num. All spectra then have the same length.

Transfer of Data in Memory

Is used only independent of spectra substructure. A transfer is basically from to length "title" id
    tr start_addr first address
       new addr   second address to which data are moved
       length     number of channels to be transferred.
       "title"    optional name, used in ls.
       id         optional new id
    tr 2k 0 2k	transfer two K of data from second
		to first K
    tr [CR]	uses former numbers again
    tr w 10k 2k transfer data from work area to 10k (2k long)
    tr w+2k 8k 2k "bkgd" 5
    tr w        work area data are transferred to 'end' of used data space
                simplifying space selection

Write Data File

    w File_name	Name of output file
      startaddr	Start address of data set
      length	number of channels
The output file is written in the standard data format. The spectra organization present in memory is kept in the file header. Examples
    w file 2k 4k 3  stands for write file of 4096 
		    channels beginning at address 2048.
		    and set run_number to 3

    wf name	    writes data as floating numbers.
                    If only a file name is provided the data of the work area
                    are written out.

    wspe name       writes data of the work area as .spe (Radware) file
    wspe name 4k    writes independent of actual length 4k data to the file
    wasci name      writes data (work area) as ASCII list to file

The File menu entry Save brings up a message dialog for writing data to disk.

Write Marks

Saves marker array in file with extension .mks (marks).
See read back
    wmarks filename	stores the marker array.
This effectively makes a suspension of XSA possible. To resume start XSA read data and marker file and continue.

Write Windows

A file containing marker pairs for sorting cuts is written to disk with an extension .win. A .win file is written in ASCII format.
    ww name
There is also a rw command to read windows back.

Zero Data Region

    zero id           zero spectrum
    zero first ch     first channel
         last ch      last channel
The channel numbers refer to the total histogram array. If last channel is less than first, last ch is taken as length. Examples
    zero 2         zero spectrum with id = 2
    zero 1 3 6 - 9 zero spectra 1 3 6 7 8 and 9
    zero 0 1k	   clear first K of current spectrum
    zero all	   zero all data
    zero reset     clear all spectra and reset number of histograms to 0
    clear          synonym for zero reset
    zero w         zero workspace (all 16k)

Set Data

Sometimes it is useful to set a data point or region.
    set channel new-Data
    set new-Data
               and click in window (between 2 marker).

Transient field Analysis

XSA has built in special functionality for the analysis of spectra containing small differences in counting rates in selected peaks. Such spectra are typically taken in perturbed angular correlation measurements for two magnetic field directions at the target.

A special set of commands is provided: ud,rat,anis.

Begin up-down mode

Assume a four detector setup symmetric to the beam direction;
two detectors at a backward angle and two detectors at a forward angle. From a small difference in the peak area of a γ line the rotation of an angular distribution for two settings of a magnetic field at the target (UP and DOWN) has to be determined.
The data contain at least two sequential spectra per detector, one UP spectrum and one DOWN spectrum. For coincidence data usually two more spectra are required containing random counts, for a total of 4 spectra per detector (up_prompt, down_prompt, up_random and down_random).
Usually the same peaks is analyzed in all spectra (4 spectra per detector). To keep separate peak integration marks for each detector, it is recommended to mark the peak for each detector individually.

When typing

   ud 1
in the command line the data of detector 1


(the average of UP and DOWN) is put in the work area as first spectrum followed by (UP-RANDOMS)and followed by (DOWN-RANDOMS).
If peaks are marked, peak 0 (zero) and surroundings is shown, else the whole spectrum is displayed and peaks have be selected.
Proceed with the usual peak integration. Peaks can be summed or fitted. The results for UP and DOWN are separately displayed. Both, the UP and DOWN spectra are analyzed with the same set of marks. The slope of the background is taken from the average spectrum, but the constant term is individually determined for ud and down.
This has to be repeated for all detectors.

   ud 2
   ud 3
   ud 4
The corresponding peak sums (up and down for detectors 1 to 4) are stored and then used for the double ratio calculation rat.
As a short cut 'n' in the graphics window moves from ud 1 to ud 2 and so on.
If more than one peak in a spectrum should be analyzed, the second peak has to be marked 4 ,5, 6, and 7 (for detectors 1 - 4 respectively) and so on. Up to 25 transitions in a measurement can be processed at one time, but often it is simpler to work on one peak at a time.
   ud ndet id np   select detector, id of first spectrum and peak group
For each detector ndet the 4 spectra starting at a given id are selected for analysis. The default id is 1.
The id and peak group np is only read with ndet == 1. np is 0 for the peak group 0 1 2 3 and 1 for the peak group 4 5 6 7 and so on.
The order of the spectra for the 4 detectors is assumed to be
det 1 ud+r dw+r rup rdw
det 2 ud+r dw+r rup rdw
the first spectrum if not 1 has to be set in the ud command.

Double Ratio

After peaks for all 4 detectors are analyzed, special double ratios of the counting rates for each peak are calculated.
    rat np number
np is 0 for peaks 0-3 (1 for peaks 4-7 and so on) and number is the number for how many of such peak groups ratios should be calculated. Examples
    rat 0 1    only the ratio for the first peak group is calculated.
The peak areas are logged in a file, default name "rlog.dat", for further analysis. This default name can be overwritten.
    rat 0 1 > newfile
The new file name is in effect until changed or the program is restarted.

In principle 2 detectors are sufficient for a double ratio. Check the command

     rat2 det1 det2
calculates a double ratio for two detectors, which have to be provided where det1 det2 are the numbers of the detectors.

If the logarithmic slope is given (Options -->Sa Anisotropy), it can be typed in, if known, it is used to calculate the precession angle Δθ.


Anisotropy ratios

The coefficients A2 and A4 and η of a particle - γ angular distribution can be derived from an anisotropy ratio, the angular distribution measured at two angles. The anisotropy ratio is measured with a minimum of two γ detectors, both placed once at two different but opposite angles. From double ratios of the peak rates a ratio of the intensity at the two angle positions independent of detector efficiency and time for each measurement is derived. For the calculation, the peak intensities are assumed to be stored in a specific order (det1-high, det1-low, det2-high, det2-low), where high and low refers to the detector angle for which the intensity is higher or lower. In the Options menu is a widget to select all needed parameters.
Returned are A2, A4 and the logarithmic slope for Angle_3 used to calculate precession angles from effect ratios (rat).
For this to work, the order of the peak information should be as follows:
If the spectra are ordered in this sequence, the sran 1, sran 3, .... sran 15 command sequence puts the data in the proper order. This can be done by arranging the spectra in memory in the proper order before running sran (subtract randoms).

anis can also be used with a known anisotropy ratio.
The command is

     anis R δR
where R is the ratio and δR its error.


Peak sums with subtraction of randoms

Coincidence data usually come as two spectra: TRUE+RANDOMs and RANDOMs.
Most often the RANDOMs spectrum follows directly the TRUE+RANDOMs spectrum. The command sran helps in the peak analysis, where the randoms subtraction contributes to the error of the peak sum.
    sran id
The spectrum with id is put into the work area with the random spectrum subtract. Mark and select a peak of interest, sum or fit peak. The random subtraction is included in the peak area error when written out.
    sran id1 id2
id2 is the id of the randoms spectrum if other than id1+1.
    sran id1 p #
a p (for peak) with a peak number can be added in the command line to select a peak for immediate summation.
Since this command invokes the random summation in the process, it puts XSA in a special mode, which is canceled only when the s or i command is used to write out the result.

Miscellaneous Commands

    scale # #   creates a channel by channel scale factor spectrum
                from summed windows.
    system      invoke system call (like 'date', 'echo' ...)

EXIT Program

    exit[CR]	normal exit of program.
    quit[CR]	The log files are removed on exit. 

Command List Summary


      "ds"     :  display 1 or more spectra                    ( disp     )
      "do"     :  overlay spectrum			       ( disp_o   )
      "ov"     :  overlay list of spectra                      ( overlay  )
      "d"      :  redisplay or display selected region	       ( disp_d   )
      "dsr"    :  set display range			       ( set_dsr  )
      "log"    :  display in log scale (subtract decade)       ( logdis   )
      "lin"    :  display linear			       ( lindis   )
      "setid"  :  toggle use of file / data space id 	       ( set_id   )

Data input/output

      "r"      :  read whole file			       ( readfile )
      "ra"     :  read whole file and append		       ( readfile )
      "rs"     :  read selected spectrum from file	       ( readspec )
      "rc"     :  read matrix data, select columns	       ( readcol  )
      "rr"     :  read matrix data, select rows	               ( readrow  )
      "file"   :  open datafile for reading		       ( get_fln  )
      "open"   :  open datafile for reading		       ( get_fln  )
      "cd"     :  set path for reading data files	       ( chpath   )
      "pwd"    :  show directory from where data are read      ( prpath   )
      "w"      :  write new file (integers)		       ( wrtf0    )
      "wf"     :  write new file (floating numbers)	       ( wrtf2    )
      "wspe"   :  write Radware file .spe                      ( wspe     )
      "wasci"  :  write ASCII data to file                     ( wasci    )
      "tr"     :  transfer data in memory		       ( trans    )
      "sel"    :  select (copy) spectra in work area	       ( sel_id   )
      "ls"     :  list spectra in memory		       ( shspec   )
      "zero"   :  purge spectra from memory		       ( zero_dat )
      "clear"  :  clear all data space		               ( clear    )
      "ps"     :  create postscript picture file	       ( psfile   )
      "ps1"    :  create 1 col. multiple spectra ps file       ( psfile   )
      "ps2"    :  create 2 col. multiple spectra ps file       ( psfile   )
      "pso"    :  create postscript data in overlay mode       ( o_psfile )
      "lps"    :  send postscript picture to printer	       ( p_psfile )
      "lpso"   :  same for overlay mode		               ( po_psfil )
      "pd"     :  print data as vector list (sa.dat)	       ( pridata  )
      "pdg"    :  print data as xmgrace data file	       ( pridata  )


      "cal"    :  calibrate energy scale		       ( calibrat )
      "cpcal"  :  copy calibration to display region	       ( cpcal    )
      "wcal"   :  write calibration data to file	       ( wcal     )
      "esc"    :  toggle energy scale display		       ( escale   )
      "m"      :  mark; type channel number to be marked       ( set_mark )
      "mm"     :  move[mark] one/several marks to new position ( mv_marks )
      "reset"  :  clear all marker			       ( reset    )
      "rm"     :  read marker file back		               ( rmarks   )
      "rmarks" :  read marker file back		               ( rmarks   )
      "wm"     :  write marker file to disk  (.mks)	       ( wmarks   )
      "wmarks" :  write marker file to disk  (.mks)	       ( wmarks   )
      "ww"     :  write window (marker pairs) to disk (.win)   ( w_win    )
      "rw"     :  read window file back		               ( r_win    )
      "p"      :  select marked peak for integration	       ( peak     )
      "pm"     :  import peak marks from an other peak         ( peakmar  )
      "i"      :  sum peak (integrate)			       ( integrat )
      "f"      :  fit Gaussian to peak[s]		       ( fit      )
      "aps"    :  set automatic peak search factors	       ( set_aps  )
      "nspec"  :  set number of spectra (work area)	       ( set_flhd )
      "set"    :  set individual data point in spectrum        ( data_set )
      "sum"    :  sum content for list of window	       ( sumlines )


      "add"    :  add spectrum to data in work area	       ( add      )
      "addc"   :  add a constant to all channels	       ( forge    )
      "sub"    :  subtract spectrum from data in work area     ( sub      )
      "sran"   :  subtract two spectra and put in work area    ( subran   )
      "mulf"   :  multiply data in work area by a factor       ( forge    )
      "div"    :  divide two spectra			       ( divide   )
      "mul"    :  multiply two spectra			       ( multiply )
      "smooth" :  smooth data				       ( smooth   )
      "sqrt"   :  make square root of data in work area        ( forge    )
      "gmf"    :  set shift and gain change factors	       ( set_scf  )
      "gm"     :  apply shift and gain change		       ( g_match  )
      "scale"  :  select scale factors (special feature)       ( scale    )
      "cut"    :  cut negative data of spectrum	               ( forge    )
      "ful"    :  "flat upper limit" background subtraction    ( genful   )


      "ud"     :  select data set for up/down analysis	       ( udselect )
      "anis"   :  calculate anisotropy ratio                   ( anis     )
      "rat"    :  for u/d analysis make 4 det. double ratio    ( dratio4  )
      "rat2"   :  for u/d analysis make 2 det. double ratio    ( dratio2  )


      "run"    :  run command list file		               ( runfile  )
      "system" :  execute shell command		               ( dosystem )
      "exit"   :  exit XSA 				       ( exitus   )
      "quit"   :  exit and delete log files		       ( quit_pro )

Environment variables

      UIDPAHT: export UIDPATH=/usr/local/uid/%U%S     for xsa.uid
      XSAPS:   export XSAPS=/usr/local/...            where preamble.ps for
                                                      postscript files is stored.
      XSACMD:  export XSACMD=/usr/local/share/....    where mk-files are collected
back Up to Outline.

Back to Rutgers Physics Home Page

Gerfried Kumbartzki
Last modified: Fri Dec 14 15:39:33 EST 2012