Spectrum Analysis

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 button-press events are used to manipulate the picture.

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 a File. An 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). For 'online' applications the shared memory segment can be filled by a separate histogram process.

      Total data space available   440k
      Work area                     16k
      

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, all data can be viewed and manipulated 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).
Important restriction!
When accessing the data array as a whole, keep in mind that the zero point is the start point (array offset) of the last called spectrum. A call to the first spectrum selects as zero point the begin of the data array.

Commands

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. Line commands consist of a code word and input in form of text 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.
A general advice: Spectra should be changed, when possible, only in the work area.
One or more spectra are copied into the work area using the sel id command.
First select a spectrum (sel id) then call the action.

Typical Tasks

• Add data
• Add constant
• Command_file Mode
• Energy Calibration
• Display Spectra
• Gain Match Spectra
• Multiplication/Division of Spectra
• Multiply data by Constant
• Mark Position - Move Marker
• List Spectra
• Print Data/grace file
• Postscript Picture
• Peak Integration or Peak(s) Fitting
• Read Data
• Read Marks
• Read Variable
• Reset (clear) Marker Array
• Set output File Head
• Shift marks
• Subtraction of Spectra
• Transfer of Data in Memory
• Write Data File
• Write Marks
• Write Windows
• Zero Data Region
• Set Data
• Transient Field Analysis
• Miscellaneous Commands
• EXIT Program
• Command List Summary

Add data (adding spectra)

Adding spectra puts the sum into the work area. The add command adds the data to the content in the work.
A typical command sequence would be

   sel  id      put spectrum with id in work area
   add  idx     add spectrum with id idx to the first and display
                the result in the  work area.
      

Examples

	sel 1
	add 2 3 4 will add the three spectra to the content (spectrum 1) in
                  he work space.
        add 2 - 8 will add 2 3 4 5 6 7 and 8
      

Add constant to data

    addc constant       to spectrum in work area.

    addc constant id    addc constant to spectrum with id

    addc constant	to be added to each channel
	[first ch]	start of spectrum
	[last ch]	last channel
      

    addc 23 0 1k	expands to
			add 23 to the first 1024 data words.
      

Command_file Mode

A command file is a list of input lines as typed in the command widget.
For instance: Edit a cmdfile (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 at address 4096
   add 0 4k 4k       ;add file2 to file1
   w file3 0 4k      ;write sum spectrum (now in 0) to file3
      

Execute the file by calling

   run  filename
      

Examples

Assume the command file "mkread" is:

     open $1par.his
     rs $2

     mkread sma 0  or
     mkread smb 3

Energy Calibration

The number of input tokens determines what is expected:

  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.

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

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

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

  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.

  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 (see Options menu).
      

Display Spectra

  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).

  do id		plots data over old picture.
  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 0  A 'zero' as last number invokes auto scaling for the overlaid
                spectrum.
  ov id         similar to 'do id'. In addition it has the
                functionality of the 'ds' command.
  ov 2 4 5      overlayes on the current display spectra 2 4 and 5.

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).

Display Commands

Use of mouse buttons:

• left BTN:
  change input focus, show channel number and content, button down - move - button up expands the part of the spectrum.
• middle BTN:
  mark position
• right BTN:
  label position as energy or channel number

Display command list in alphabetical order:

a

automatic peak search. Peaks are marked (Max 100).

b

calculate and display background. After b a number between 0 and 5 has to be typed immediately. This number is the order of the polynomial for the background fit (bb uses the last order again, b- no background). 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.

f

fit up to 4 Gaussian to selected data (see peak).

g

grab/ungrab nearest marked peak for integration or fit. If no peak is marked, select around cursor.

j

display selected region - 1024

h

display selected region + 1024

k

kill last marker.

l

toggle between linear and log display.

m

set a marker at cursor position (Same middle mouse button press).

n

next - display higher data region. In peakmode select next peak.

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 (formerly i).

t

type marker shown in display window (channel number, energy and data).

u

update, redo peak.

x

start expand. After typing x move the cursor and type x again, the range (region) between the two cursor positions will be expanded. Same press left mouse button drag and release. If the channel has a mark the mark is moved

y

set new y-scale to vertical cross-hair cursor.

z

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).

,

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.

1-9

Immediate shift of that marker to new cursor position.

space

enlarges window in steps.

<      "move" histogram in window to left.

>      "move" histogram in window to right.

Gain match Spectra

   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.
   gm id     does the matching. The result is in the work space.

    gmf 0.5 0.0	the new spectrum will be half the length
    gm id       and be in the work area.

    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.
                 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

After for all detectors the reference positions were determined

    pp out  (0 is equivalent to out)

    pp nr

    pp
    ds 1

Multiplication/Division of Spectra

    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.

    div  addr1	start address of data in array
         addr2	start address of other data
         length	total number of channels

Examples

    div 0 3k 1k	will be expanded as, divide 1024 (1K)
		data starting at 3072 by data starting
		at 0 and leave the result in K0.

Multiply data by Constant

   mulf factor	multiplies whole spectrum in  work area

   mulf factor id
		multiplies data in spectrum id.

   mulf 1.25 0 1k
		expands into multiply all channels of the
		first K by 1.25.

Mark Position - Move Marker

    m number	where number is the channel number or
		energy if a calibration is provided

    mm # [#] [#]

List Spectra

                Pull down File menu and choose listing or
    ls		all spectra  in core are listed:
		index,id,name,begin in array,length,calibration data

    setid	toggles between id and index. id is default (see Options
menu).

Print Data

    pd first_channel last_channel
    pd first_channel last_channel > filename

    pd 100 150	the data of the channels between
		100 and 150 will be printed out.

    pdg (same as above)

Postscript Pictures

   ps

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 picture.

   ps 1 2 "Detector 3"

Spectra 1 and 2 with a heading 'Detector 3' are written into sagraph.ps

    ps 1 "Title" > newname.ps (changes output file name)

If only one spectrum is selected;
Landscape format is used,
all marks set in that window or region will be converted into channel numbers or energies (if calibration present). If the highest channel is marked a centroid using the adjacent channels will be calculated.

The command lps sends the ps file directly to the default printer. Equivalent: Print of file menu which 'copies' the screen.

Graphs can be overlaid (in colors) using pso instead of ps like in

   pso 2 5 -ymax

If the last entry is a negative number, it is used as YMAX for all spectra. -1 in overlay mode invokes auto scaling for each spectrum.

   pso

An overlay picture can also be printed using the current screen layout (preserving the yscales).

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

One spectrum is always plotted using LANDSCAPE format. ps1 plots spectra in 1 column (PORTRAIT). 1-8 spectra fit on one page.

    ps1 2 - 5 > name.ps
        spectra 2 3 4 5 are written in postscript file 'name.ps'.

ps2 does the same in 2 columns. Up to 16 spectra fit on one page.
back

Peak Integration or Peak(s) Fitting

In command mode peaks are called by their marker number.

    p peak_no	peak number
      width	optional width of display window
		Default is 64 left and right of peak.
    pm peak_no  imports all peak marks from the specified peak

Examples
    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.

The peak and a window around the peak will be displayed. Set marker 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-. In this case only two marks (0 and 1) need to be set.

A simple summation is started with s 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 bkgd should be set zero all marks have to be set.

The results are written to the screen and to the file sa.dat (check file results.dat), which contains shortened information 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.

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

Examples

    ds 1         thats 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)

Examples

    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 Data

r

read whole file at once

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 independent of their file format.

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

    r myfile 2k	myfile is read and stored from address
		2048 up-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.

    r myfile a  the next data are appended to the data array.

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

    rs myfile 1 0
		myfile spectrum with id 1 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).

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.

File Header

  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 */
  };

	flhd.maxid         = 1;
	flhd.sinfo[0].id   = row_length;
	flhd.sinfo[0].offs = column_length;

Read Marks back

    rmarks filename of marker file.
    rm     (for short)

Read Variable

    rv name value

    rv thet3 70.0
    rv thet1 50.0
    rv q2 0.97

Reset Marker Array

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

Set output File Head

    sflhd num	   select number of spectra

Subtraction of Spectra

Transfer of Data in Memory

    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

    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

    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.
back

Write Marks

    wmarks filename	stores the marker array.
    wm

Write Windows

    ww name

Zero Data Region

    zero id           zero spectrum
    zero first ch     first channel
         last ch      last channel

    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

Set Data

    set channel new-Data
    set new-Data
               and click in window (between 2 marker).

Transient field Analysis

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

Begin up-down mode

    ud ndet id np

Double Ratio

    rat np number

    rat 0 1    only the ratio for the first peak group is calculated.

    rat 0 1 > newfile

In principle 2 detectors are sufficient for a double ratio.

     rat2 det1 det2

back

Anisotropy ratios

    anis

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

     anis R dR

Peak sums with subtraction of randoms

    sran id

    sran id1 id2

    sran id1 p #

Miscellaneous Commands

    esc         toggles between Energy scale and Channel numbers
    cd [path]   change data directory
                without path reset to starting directory
    ls          list what is in memory
    ful id      ful creates a background free 
                spectrum of id in work area plus the 
                background next (adjacent) in the work area
    pwd         show the current data directory
    rebin nk    rebins current spectrum to new (nk) length (e.g.2048 -> 1024)
    setid	toggles between id and index.
    scale # #   creates a channel by channel scale factor spectrum
                from summed windows.
    shift ch    shift current id spectrum by ch channels.
    sqrt        makes a sqrt spectrum from current id.
    sum         sum Peak Integration or Peak(s) Fitting
                between marker pairs, write to results.dat
                useful after using ful background subtraction.
    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

Display

      "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 )
      "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   )
      "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  )

General

      "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    )
      "rmarks" :  read marker file back		               ( rmarks   )
      "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 )

Spectra

					                   
      "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   )

Transient

      "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  )

Misc

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

Up to Outline.