"gaspan" is a program to analyse spectra with lines of symmetric or asymmetric Gaussian shape using a peak search routine and a nonlinear fitting algorithm. Tails and nonlinear background might be included into the fit. The fitting conditions can be tailored by specifying options and parameters of the fit. The general structure of a command is: `command` [`sub-command`] [`-option`]=`[parameter]` All input can be abbreviated to the amount that it is still unique, i.e. the command `help` can be abbreviated to `hel`, `he` or `h` whereas the command `get` can not be abbreviated because there is also a command `generate`. Gaspan command lines are subject to a history mechanism, i.e. old commands can be retrieved with the arrow keys and edited. A minimum input is needed for a rough fit: 1. Definition of Data: `set file -file=filename` 2. make a fit: `fit first,last-channel,[degree_of_backgr._polynomial]` The fit can also be started with the command `go`. The results are written into a file "gsp1filename", the gaspan data summary file and spectrum and fit will be displayed on screen assuming the terminal is capable of graphics. The fitting procedure can be stopped by typing CTRL C (see `fit` or `go`). Quit the program with either "q(uit)" or "e(xit)". On startup gaspan tries to read the file $HOME/.gaspanrc. Specifying options in this file will allow to change default values without the need to modify the source code. This help file is adjusted to a window with at least 80 columns. citation: F. Riess, http://www.cip.physik.uni-muenchen.de/~riess/ 1 calibrate `calibrate [filename]` Allows the calibration or recalibration of a gaspan data summary file, i.e. energy and/or efficiency calibration. A filename can be specified in the command but if it is not specified, it will be asked for one. The command is ignored if no calibration is specified at the time of its issue and an error message will be given. Calibrations can be specified with the commands `set peak -energy=filename` `set peak -efficiency=filename` or `set parameter -energy=(value of coefficients)` `set parameter -efficiency=(value of coefficients)` No error propagation will be done if the calibration is inserted via the command `set parameters`. 1 do Execute a command in the shell. In order to edit a file named "data.lst" with the editor "vi" type `do vi data.lst`. To get a listing of the current directory: `do ls` 1 exit Exits from "gaspan" and returns to the shell. Identical to the command `quit`. 1 fit `fit [min_channel,max_channel[,degree_of_background_polynomial]]` Command for interactive fitting: fits one region given either by the command `set fit -region=min_channel,max_channel` or by the optional arguments min_channel and max_channel. The degree of the background polynomial can be specified too. The size of the fit region must be less or equal the internal region size and the number of peaks in the region must be less than the maximum number of peaks in a fit region. Both numbers can be obtained with the command `show limitations`. The degree of the background polynomial must be in the range [0,4]. If the file is not present, an error message will be given and the program proceeds to the next filename. If no filename has been defined at this point, the user will be asked for. The output is switched to the interactive mode, i.e. the fit results will be printed and the fit will be displayed. The fitting procedure can be stopped by typing CTRL C. The program will return to the command loop once the current fit cycle is finished. The data of the fit will be saved. No residue search and parameter checking will be done for a stopped fit. The peak data will also be written into the file "gspNfilename" where the digits N equals the sub spectrum number and "filename" is the filename of the spectrum with any path specifications being stripped. This file is written in ASCII format and can be printed and edited. WARNING: previous fit data will be lost unless the command `set peak -append` has been given. A file "parNfilename" will be generated if the option `set fit -save` was given. This file holds binary data and can be used to reconstruct the fit with the command `show saved_fits`. Note: The most recent fit can allways be inspected with the command `show fit`. Two ASCII files "fitNfilename" and "bckNfilename" with the extensions changed to ".dat" will be generated containing the fit and the background spectrum of the fit if the option `set fit -out` was specified. An ASCII file "fithistory.gsp" will be written if the option `set fit -print` was given. A postscript file "display_file" holding postscript outputs of all displays will be generated if the command `set display -save=display_file` was given. Energies must be specified for the values of 'min_channel' and 'max_channel' if there is an energy calibration and the option `set display -energy` has been set. 1 generate `generate [filename]` Allows to construct gate spectrum from a binary "gaspan data summary" file which has been obtained with the fit option `set file -matrix` 1 get The get command reads information for "gaspan" from a file. 2 options `get options [filename]` Reads the options and parameters which have been previously saved by the command `save options [filename]` and sets them according to given specifications. If no filename is specified, the default filename "gaspan.sta" is used. The default file extension is ".sta". Previous set options are overwritten. Commands can be globally defined in the file "$HOME/.gaspanrc". 2 parameters `get parameters [filename]` Obsolete in versions 1993 and later: Parameters are save together with the options. Use the command `get options [filename]` 1 go Starts the fitting procedure. If no filename has been defined at this point, the user will be asked for. If the file is not present, an error message will be given and the program proceeds to the next filename. The program will search for peaks in the specified region and will define fit regions on the basis of this peak list. A list of peaks and/or a list of fit regions can be provided externally (`set peak -list=` and `set region -list=`). The fit regions are fitted subsequently starting from low channel numbers to large channel numbers. If the program returns to the command interpreter without the message ... working on ... no fit has been done and the analysis region should be checked to insure that it overlaps with fit regions if defined and that there are lines in the region specified. The program will return to the command loop once the fit cycles are finished. The fitting procedure can be stopped by typing CTRL C. The data of the fit will be saved. No residue search and parameter checking will be done for a stopped fit. The peak data will be written into the file "gspNfilename" where the digits N equals the sub spectrum number and "filename" is the filename of the spectrum with any path specifications being stripped. This file is written in ASCII format and can be printed and edited. WARNING: fit data of previous go or fit commands will be lost unless the command `set peak -append` has been given. A file "parNfilename" will be generated if the option `set fit -save` was given. This file holds binary data and can be used to reconstruct the fit with the command `show saved_fit`. Note: The most recent fit can allways be inspected with the command `show fit`. Two ASCII files "fitNfilename" and "bckNfilename" with the extensions changed to ".dat" will be generated containing the fit and the background spectrum of the fit if the option `set fit -out` was specified. An ASCII file "fithistory.gsp" will be written if the option `set fit -print` was given. A postscript file "display-file" holding postscript outputs of all displays will be generated if the command `set display -save=display-file` was given. 1 help "gaspan" is a program to analyse spectra with Gaussian peaks by a least square method. Deviations from a Gaussian peak shape can be handled by adding left or right exponential tails to the peak. A background polynomial of up to fourth degree is included in the fit. Asymmetric background around the peaks can be taken care of by including an exponential left side tail with long decay constant ("background tail") and/or a step function. Peaks can be either found by a peak search routine and a residue search or by defining a list of peaks. The same is true for fit regions. The working mode of "gaspan" can be defined by setting options with the `set` command. Fit parameters and/or fit displays can be saved to review the fit at a later time. 1 quit Exits from "gaspan" and returns to the monitor. Identical to the command `exit`. 1 save Allows to save the current settings of options and parameters. 2 option `save option[ filename]` Saves the current settings of the parameters and options in the specified file. The default file type is ".sta". If no filename is specified, the default filename "gaspan.sta" is assumed. The options and parameters are not changed. 2 parameters `save parameters [filename]` Obsolete since 1993. Use `save option [filename]`. 1 set Defines "gaspan" analysis modes and/or fit parameters. 2 background Defines the parameters for calculating a background polynomial in channel number in the fit region. The polynomial can be up to 4th degree. The size of the background can be fixed to a specified value if the polynomial degree of the background is chosen to be 0. The coefficients of the background polynomial are listed in the file "fithistory.gsp". See `set fit -print`. In addition a tail on the left side of a peak and/or a step function with amplitudes proportional to the height of the peak can be added to the background. See options `set tail -background` and `set tail -step`. 3 -fit The background polynomial is fitted with a degree specified by either `set background -polynomial_degree` or `set background -max_polynomial_degree`. In the latter case the program will make a decision on the degree of the background polynomial on the basis of the size of the fit region and the statistical relevance of the data. Equivalent to `set background -nofixed`. Default. 3 -fixed=(%f) `set background -fixed=value` Fixes the size of the background to the specified value. Works only with the degree of the background polynomial set to 0. Equivalent to `set background -nofit=(%f)`. 3 -nofit `set background -nofit=value` Fixes the size of the background to the specified value. Works only with the degree of the background polynomial set to 0. Equivalent to `set background -fixed=(%f)`. 3 -nofixed The background polynomial is fitted with a degree specified by either `set background -polynomial_degree` or `set background -max_polynomial_degree`. In the latter case the program will make a decision on the degree of the background polynomial on the basis of the size of the fit region and the statistical relevance of the data. Equivalent to `set background -fit`. Default. 3 -max_polynomial_degree=(%d) `set background -max_polynomial_degree=value` Allows to specify the maximum polynomial degree which is to be used in the fits. A smaller polynomial degree might actually be used because "gaspan" tries to get an estimate for the polynomial degree using the size of the fit region and the quality of the statistics of the data. "value" must be a number in the range [0,4]. Default with value = 2. This qualifier is mutually exclusive to the qualifier `-polynomial_degree=`. 3 -polynomial_degree=(%d) `set background -polynomial_degree=value` fixes the degree of the background polynomial to the value specified. "value" must be a number in the range [0,4]. This qualifier is mutually exclusive to the option `-max_polynomial_degree=`. 2 display Display of spectrum and fit is possible assuming the terminal used is capable of handling X-Windows graphics. 3 -centroid Channel markers show the position of the centroid of a peak. Only important with asymmetric peaks. This qualifier is mutually exclusive with `-gauss-position` and `-tail_include` 3 -channels Displays x-axis and peak positions in channels. This qualifier is mutually exclusive with `-energy`. Default option. 3 -comment `set display -comment=string` Allows to specify a comment in the display of the spectrum. "string" will be shown in the display of the spectrum and the fit. If the string contains special characters it should be put into quotes "". A comment can be erased by using the command `set display -comment=""`. 3 -energy Displays the peak positions in energies if an energy calibration is given. The channel numbers will be rescaled to yield a linear scaling in energies. This implies that there is a unique corresponds between channels and energies, otherwise part of the spectrum will overlap with other parts of the spectrum. An energy calibration containing negativ powers in channel numbers will not have an unique correspondens at low energies. The spectrum will be shown in such a case only down to the minimum energy given by the energy calibration. The limits in the command `show spectrum min,max` and `fit min,max,[n]` must be specified in energy units rather than in channels. This qualifier is mutually exclusive with `-channels`. 3 -errorbar Displays the spectrum as points with error bars. Points outside the y-scale will not be shown. This qualifier is mutually exclusive with ` -histogram`. 3 -gauss-position Channel markers show the position of the Gaussian peak. This is only important with asymmetric peaks. This qualifier is mutually exclusive with `-centroid` and `-tail_include`. 3 -histogram Displays the spectrum as histogram. Data points outside of the y-scale are diplayed at the limits specified by the y-scale. This qualifier is mutually exclusive with `-errorbar`. Default. 3 -hold Asks for terminal input after each display in order to proceed. This option can be negated with the qualifier `-nohold`. 3 -intermediate Show intermediate displays of the fit during the fitting procedure. This option can be disabled with the qualifier `-nointermediate`. 3 -linear Displays the spectrum with a linear y-scale. This qualifier is mutually exclusive with `-logarithmic`. Default. 3 -logarithmic Displays the spectrum with a logarithmic y-scale. This qualifier is mutual exclusive with `-linear`. 3 -noerrorbar --> Use the qualifier `-histogram`. 3 -nohold Disables the option `-hold`. Default 3 -nointermediate Shows the final fit result only. Default. 3 -noresiduum No residue spectrum will be shown. The size of the spectrum is increased utilizing the free space. 3 -nosaveall Switches the option `saveall` off. Default. 3 -nosingle_peak Draws only spectrum, fit and background fit if the command `show fit` or `show saved_fits` has been given. Default. 3 -off Turns the graphic mode off. Not active with the commands `show spectrum`, `show fit` or `show saved_fits`. This qualifier is mutually exclusive with `-on`. 3 -on Display the spectrum and its fit during the fitting. On each fitting sequence the following spectra will be shown: - The fit spectrum and the background polynomial as continuous lines, - the fitted spectrum either as a histogram or dots with error bars, and - the residue spectrum with the statistical limit corresponding to two standard deviations. The peaks included in the fit are shown by vertical bars marked by the channel number (i.e. energy). A header text displays the filename, the degree of the background polynomial, tails if they are included in the fit, the number of peaks and the normalised chi square. 3 -print `set display -print=output_device` Allows to define the queue for a printer for the output of the graphic display. "Gaspan" generates postscript files which can be printed by any printer capable of postscript. Examples: `set display -print=lpr` (default) `set display -print="lpr -Pprinter_name"` 3 -residuum When a fit is shown, the residue spectrum will be shown too. This space is left free in the command `show spectrum`. Default. 3 -saveall `set display -saveall=filename` Save all displays shown on the screen in the file "filename". Each saved display will be on one page of the postscript file "filename". This option can be disabled with the option `-nosaveall` 3 -single_peak Draws each single peak if the command `show fit` or `show saved_fits` has been given. This mode can be switched off with the option `-nosingle_peak`. 3 -tail_include Derives the position of the peak markers from the command `set tail -include`. Mutually exclusive with the qualifiers `-gauss-position` and `-centroid`. Default. 3 -windowsize `set display -windowsize=xsize,ysize` Allows to change the size of the window in which the spectra are shown. xsize and ysize are the size of the new window in fractions of the screen size, i.e. the command `set dis -win=1.,1.` will generate a window which covers the full screen. Values greater than 1 or less then 0.575 for xsize and 0.35 for ysize are set to these limits, respectively. The old window will be destroyed before the new one is generated, the contents of the old window is lost. Default vaues are xsize=1.0, ysize=0.7. 3 -yscale `set display -yscale=[ymin],[ymax]` Allows to specify the y-scale of the displayed spectrum. The numbers are optional but the colon is mandantory. A number which is not specified will be derived from the spectrum, i.e. the command `set display -yscale=,` specifies, that both numbers are obtained from the spectrum. "ymin" will be ignored if it is larger then the maximum of the spectrum, "ymax" will be ignored if it is lower than the minimum of the spectrum being displayed. Data points below "ymin" and above "ymax" will not be displayed in the mode `set display -errorbar` and will be shown at these limits in the histogramming mode. The command is fully effective only for a linear y-scale. "ymin" and "ymax" will be expanded to powers of 10 in a logarithmic scale. NOTE: This command is ignored by the commands `show options` and `save options`. 2 files Allows to specify a filename for the spectrum and defines the data format of the spectrum either from the extension or by an option. 3 -file `set files -file=filename` `set files -file=filename,sub_spectrum` `set files -file=filename,first-spectrum,last-spectrum` `set files -file=filename,first-spectrum,last-spectrum,increment` `set files -file=path/filename[,first-spectrum[,last-spectrum[,increment]]]` `set files -file=@filename` The parameter specifies the filename of the file containing either one spectrum or several spectra. If a data file contains several spectra, the first spectrum in the file will be analysed unless "first-spectrum" is specified. If "last-spectrum" is also defined, "gaspan" will analyse all sub spectra between first- and last-spectrum with increment of 1 unless "increment" is defined too. A path can be specified if the data file is not in the working directory. If the filename is preceded by a concatenation sign (@), it is assumed that this file contains a list of filenames to be worked at. A warning will be given if the specified file is not present. The files might be compressed with extensions ".Z" or ".gz". Uncompressed data files will be generated in the directory /tmp/. The user must have write permission in the working directory. "gaspan" will generate at least one output file: the gaspan data summary file "gspNfilename" where N is the sub spectrum number (note: if there is only one spectrum in the data file, N = 1). See options `fit` and `go` for more information. 3 -format `set files -format=FORMAT` Allows to specify the data format in the input file. The following file formats are standard: FORMAT = ascii extension: *.ascii The file is assumed to be an ascii file with a header (i.e lines which contain at least one non numerical character) and a sequence of channel contents, at least one per line, and a length of line less than 130 characters. Several spectra ("sub spectra") might be in one file, separated by headers. Sub spectra are addressed by the sub spectrum number. FORMAT = dat extension: *.dat The file is assumed to be an ascii file with a header followed by lines containing [channel [sub_spectrum]] contents values in [] are optional. Spectra are assumed to start with channel 0 if channel numbers are not given however channel 0 is always ignored. Channel and sub spectra numbers must be integer numbers with either integer or float representation. The contents might be integer or floating point numbers also with exponential representation. Several spectra in one file - separated by a header - are permitted if the sub spectrum number is not present. They are addressed with the sub spectrum number. FORMAT = daterr extension: *.daterr The file is assumed to be an ascii file with a header followed by lines containing [channel [sub_spectrum]] contents error values in [] are optional. Spectra are assumed to start with channel 0 if channel numbers are not given however channel 0 is always ignored. Channel and sub spectra numbers must be integer numbers with integer or float representation. The contents and its error might be integer or floating point numbers also with exponential representation. Several spectra in one file - separated by a header - are permitted if the sub spectrum number is not present. They are addressed with the sub spectrum number. FORMAT = search The program decides on the basis of the extension (.ascii, .dat, .daterr etc) which file format is to be used. Default. Information about other formats implemented in the current version of "gaspan" can be obtained with the command `show limitations`. 3 -helpfile `set file -helpfile=path/gaspan.hlp` Allows to specify the full filename inclusive path for the help file. 3 -matrix If the file specified contains several spectra it is assumed that these spectra are from the same source but with different gating conditions (i.e. coincidence data). There will be one output file ("gspfilename") of binary data. The command `generate` can be used to proceed with the analysis of this binary file. This option should be used to analyse matrices of spectra. A peak list (`set peak -list=...`) is mandatory for such an analyses. This qualifier is the complement to the `-single_spectrum` qualifier; both are mutually exclusive. 3 -single_spectrum If the file specified contains several spectra it is assumed that these spectra are independent from each other. This implies that there will be one output file ("gspNfilename", N = sub_spectrum_number) for each spectrum. This qualifier is the complement to the `-matrix` qualifier, both are mutually exclusive. Default. 2 fit Allows one to set and cancel different options which relate to the fit procedure. 3 -background obsolete, use `set background ...`. 3 -interactive Allows interactive fitting. A typical cycle will be: Define a fit region with `set fit -reg=n,m`, inspect the spectrum in this region with the command `show spectrum`, readjust the fit region if necessary and start a fit with the command `fit` or `go`. Peak centroids and peak areas will be output onto the screen after the fit is done. This option can be disabled width the command `set fit -nointeractive`. 3 -nobackground obsolete, use `set background ...`. 3 -nointeractive Disables the option `-interactive`. This option must be set, if "gaspan" is used in batch mode, i.e. in the form "gaspan < input_file" where "input_file" is a file containing a set of gaspan commands. Default. 3 -noout Disables a previous specified option `set fit -out`. Default. 3 -noprintout Disables the previous command `set fit -printout` and closes the file "fithistory.gsp". Default. 3 -noresidue_search Disables the search for unresolved peaks in the residue spectrum. This option should be used only for a rough fit to get an idea about the peak width as a function of channel number for a proper width calibration. 3 -nosave Disables the saving of the fit parameters for later inspection. Default. 3 -out The fit spectra and the background spectra of a fit of a datafile "name.ext" will be saved in a file "fitNname.dat" and "bckNname.dat" where N is the sub spectrum number. The files start with a header, followed by the first channel of the fit region in dat-format i.e. channel and contents, both as floats. The first and the last channel of a fit region are put out twice: A fit region starts and ends with channel contents zero thus allowing to recognise different fits to the same or different fit regions in one output file. 3 -printout Specifies if a printout of the fitting procedure should be done into the file "fithistory.gsp". The printout gives information about the steps made during the fit procedure: Starting values of the peak positions and information about peaks added or rejected by the different fit checking routines (loops) will be given. After each loop the elapsed time, the normalised chi square and the total number of iterations in the loop is printed. At the end of a fit, information about the peak width and tails is given (if tails are included in the fit). The file "fithistory.gsp" will be closed (and ready for inspection) if the command `set fit -noprint` is given or if "gaspan" is left with either the command `exit` or `quit`. The printout will be appended to an already existing file. This option can be disabled with the command `set fit -noprintout`. 3 -region obsolete, use `set region -fit` 3 -residue_search Poorly resolved doublets are usually not detected by the peak search routine but an analysis of the residue spectrum will detect such doublets. If this option is set, the fit will proceed until there are no structures in the residue spectrum left or the maximum number of peaks in a fitting region is exhausted (see `show limitations`). Default. This option can be disabled with the command `set fit -noresidue_search`. 3 -save This option controls whether the fit parameters are saved for later inspection with either the command `show saved_fits` or `show parameters`. The output will be written in binary format into a file with the name "parNfilename" where filename is the file name for the spectrum and N is the number of the sub spectrum in this file. Note: The last fit can be always inspected uing the command `shows fit`! This option is disabled with the command `set fit -nosave`. 2 parameters Allows one to define and change fit parameters and control the result of the fit procedure. 3 -all_check Do a parameter check of all parameters to be varied. For each parameter four steps are made: par - dpar, par -0.1*dpar, par + 0.1*dpar, par + dpar with dpar being the statistical error of the parameter. Chi square will be computed for each step by minimising it with respect to the other parameters. The change in chi square is regarded as okay if it is in the range of 0.3 and 3 by a change of dpar (the ideal value is 1). If chi square improves, the best improvement will be selected and the fit will proceed with this parameter set. See also the qualifiers `-check`, `-no check` (default), `-full_check` and `-extended_check`. 3 -background_tail `set parameters -background_tail=(a0[,a1[,a2]],d0[d1[,d2]])` Allows to specify polynomial coefficients for the amplitude a and the decay constant d of a background tail as a function of the channel number "x": a = a0 [ + a1 * x [ + a2 + x^2 ]] d = d0 [ + d1 * x [ + d2 * x^2 ]] The amplitude "a" of the tail is defined relatively to the peak amplitudes and should be a positive, nonzero number in the order of 1. The decay constant "d" is specified in channels and should also be also a positive, nonzero number > 0.5. The decline of a background tail will always be to lower channel numbers. The same number of coefficients must be given for both amplitude and decay constant. The dependence on the channel x is computed for all peaks however the values for the peaks in a fit region are varied only by factorising "a" and "d". Default parameters are provided. Warning: The decay constants of the combined option `-left_peak_tail` and `-background_tail` should be well distinct in size. 3 -check Do a parameter check of all parameters to be varied. For each parameter four steps are made: par - dpar, par -0.1*dpar, par + 0.1*dpar, par + dpar with dpar being the statistical error of the parameter. Chi square will be computed for each step by minimising it with respect to the other parameters. The change in chi square is regarded as okay if it is in the range of 0.3 and 3 by a change of dpar (the ideal value is 1). As soon as an improvement of chi square is encountered the program will return to the fit procedure with the new parameter set. See also the qualifiers `-all_check`, `-nocheck` (default), `-full_check` and `-extended_check` 3 -efficiency `set parameters -efficiency=(a1,a2,a3[,a4,[a5,[a6,[a7,[a8]]]]])` Allows to input an efficiency calibration by specifying the coefficients of the polynomial eff = 0.5*erfc[-a1^2*(E-a2)] * 10**(a3 + a4*lE + a5*lE^2 + a6*lE^3 + a7*lE^4 + a8*lE^5) lE = log10(E) with the efficiency eff and the energy E, i.e. an efficiency calibration is only possible if an energy calibration has been included. The coefficients are assumed to be free of error. Calibration points must be given in order to include the uncertainty in an efficiency calibrations. Use the command `set peak -efficiency` for this purpose. 3 -energy `set parameters -energy=(a0,a1[,a2[,a3[,a4[,a5]]]])` Allows to input an energy calibration by specifying the coefficients ai of a polynomial with positive and negative powers in the channel number (see `help set peak -energy` for a definition of the polynomial coefficients). Coefficients with positive powers in channel numbers must come first. The decision for the last coefficients to belong to negative powers in channel number is made on the basis of their size. a1 must be the linear coefficient. The coefficients are assumed to be free of error. Calibration points must be given in order to include the uncertainty in an energy calibrations. Use the command `set peak -energy` for this purpose. 3 -extended_check Do a parameter check of all parameters. For each parameter ten steps are taken between [par...par+dpar] and [par...par-dpar] with dpar being the statistical error of the parameter. Chi square will be computed for each step by minimising it with respect to the other parameters. The change in chi square is regarded as okay if it is in the range of 0.3 and 3 by a change of dpar (the ideal value is 1). If chi square improves, the best improvement will be selected and the fit will proceed with this parameter set. See also the qualifiers `-all_check`, `-check`, `-full_check` and `-nocheck` (default). 3 -full_check Do a parameter check of all parameters to be varied. For each parameter ten steps are between [par...par+dpar] and [par...par-dpar] with dpar being the statistical error of the parameter. Chi square will be computed for each step by minimising it with respect to the other parameters. The change in chi square is regarded as okay if it is in the range of 0.3 and 3 by a change of dpar (the ideal value is 1). As soon as an improvement of chi square is encountered the program will return to the fitting procedure with the new parameter set. See also the qualifiers `-all_check`, `-check`, `-nocheck` (default) and `-extended_check` 3 -left_peak_tail `set parameters -left_peak_tail=(a0[,a1[,a2]],d0[,d1[,d2]])` The amplitude a of the peak tail is defined relative to the amplitude of the peak and should be a positive, nonzero number in the order of 1. The decay constant d is specified in channels and should also be also a positive, nonzero number > 0.5. Channel dependent parameters can be entered via the coefficients of a polynomial in channels up to second order in the form a = a0 [ + a1 * x [ + a2 * x^2 ]] d = d0 [ + d1 * x [ + d2 * x^2 ]] The same number of coefficients must be given for both amplitude and decay constant. The dependence on the channel x is computed for all peaks however the values for the peaks in a fit region are varied only by factorising "a" and "d". Default parameters are provided. Warning: The decay constants of the combined option `-left_peak_tail` and `-background_tail` should be well distinct in size. 3 -nocheck Disables parameter checking. Default. See also the qualifiers `-all_check`, `-check`, `extended_check` and `-full_check`. 3 -polynomial_degree `set parameters -polynomial_degree=value` obsolete, use `set background ...`. 3 -right_peak_tail `set parameters -right_peak_tail=(a0[,a1[,a2]],d0[,d1[,d2]])` The amplitude a of the peak tail is defined relative to the amplitude of the peak and should be a positive, nonzero number in the order of 1. The decay constant d is specified in channels and should be also a positive, nonzero number > 0.5. Channel dependent parameters can be entered via the coefficients of a polynomial in channels up to second order in the form a = a0 [ + a1 * x [ + a2 * x^2 ]] d = d0 [ + d1 * x [ + d2 * x^2 ]] The same number of coefficients must be given for both amplitude and decay constant. The dependence on the channel x is computed for all peaks however the values for the peaks in a fit region are varied only by factorising "a" and "d". Default parameters are provided. 3 -step `set parameters -step=(a0[,a1[,a2]])` The amplitude a of the step is defined relative to the amplitude of the peak and should be a positive, nonzero number in the order of 1. Channel dependent parameters can be entered via the coefficients of a polynomial in channels up to second order in the form a = a0 [ + a1 * x [ + a2 + x^2 ]] A default parameter is provided. 3 -width `set parameters -width=(a0[,a1[,a2[,a3{,a4[,a5]]]]])` Allows to input a width calibration by specifying the coefficients of the polynomial fwhm = a0 [+ a1*x [+ a2*x^2 [+ a3*x^3 [+ a4*x^4 [+ a5*x^5 ]]]]] with the full width half maximum "fwhm" and the channel number x. The coefficients are assumed to be free of error. Calibration points can be used with the command `set width -calibrate`. and the coefficients of this calibration can be obtained with the command `show parameter`. 2 peak Allows to set or reset options concerning the peak positions and peak data. 3 -append The fit results will be appended to the gaspan data summary file "gspNfilename" (but not to the parameter file "parNfilename"). The file will be newly generated if it does not exist. Note: Fit options and parameters will not be appended. The append mode can be disabled with the command `set peak -noappend`. 3 -common All peak positions are shifted by the same amount to get the best fit. This option is only legal if a peak list was specified before. This option can be turned off with the command `set peak -nocommon`. The option `-common` is equivalent to `-noindividual` and `-nocommon` is equivalent to `-individual`. 3 -efficiency `set peak -efficiency=filename` Allows one to include data for an efficiency calibration either from the file "filename" or if filename=tty or =tt from the keyboard. The input data are fitted by the following function: eff = 0.5*erfc[-a1^2*(E-a2)]*10^(a3+a4*lE+a5*lE^2+a6*lE^3+a7*lE^4+a8*lE^5) with lE = log10(E) where the energy E should be specified in keV. If the input file specifies no degree of the polynomial, a degree with the best fit is searched for. A degree can be specified by inserting into the first header the line: degree: n (n = [0:5]). The format of data in the input file should be: any number of header lines followed by the data either energy efficiency error or energy error efficiency error or: a GASPAN DATA SUMMARY file with an efficiency calibration An energy calibration must be done before trying an efficiency calibration (`set peak -energy=`). Calibration sets from different sources can be accommodated in one file if they are separated by text lines. They are normalised to the first data set in the calibration file. The normalisation factors can be obtained with the option `set fit -print` from the file "fithistory.gsp". The graphic shows the data point + calibration curve followed by the difference between data and calibration followed by the fit error as function of energy. An efficiency calibration may be cancelled with the option `-noefficiency`. 3 -energy `set peak -energy=filename` Allows the inclusion of an energy calibration into the output data either from the file "filename" or if filename=tty or tt from the keyboard. The input data should have the following structure: header lines with text followed by the data either: channel energy or: channel energy error or: channel error energy error or: a GASPAN DATA SUMMARY file with an energy calibration The error of the channel number is set to 0.1 if not specified, the one of the energy to 0.01.The data are fitted to a polynomial of the kind e = a0 + sum(i=1,np) ai*x^i + sum(j = 1,nn) a(j+np)/x^j with the restrictions np >= 1, nn >= 0, np + nn <=5. If nn and np are not specified in the header of the input file with a statement "degree: nn np" the best combination is searched for involving a priority scheme which takes into account the normalised chi square, the average fit error and its variance. The user can follow this selection by setting the options `set fit -interactive` and `test print 12`. The weight in calculating chi square is calculated from the errors in energies as well as from the errors of the channel numbers. The variance-covariance matrix is taken into account when calculating the error of an energy. The graphic shows the difference between data and calibration followed by the fit error as function of energy. An energy calibration can be undone with the option `-noenergy`. 3 -fit The option `-fit` specifies that the peak positions are to be varied in the fit. Default. (see also `-nofit`). 3 -include_background_tail If a background tail is included into the fit function it will be included into the peak data. 3 -individual The positions of the peaks are fitted individually. During one fit cycle the peak position is only varied in an interval given by the width of the peaks. Default. The negation of this option (`-noindividual`) is only legal if a peak list was defined. `-individual` is equivalent to `-nocommon` and `-noindividual` is equivalent to `-common`. 3 -list `set peak -list=filename` Allows to define a list of channels contained in the file "filename" which are used as either starting points for peak positions or as a fit with fixed peak positions. A peak list might have the following format: any number of header lines peak_position peak_position width peak_position position_error width peak_position position_error peak_area area_error width A header line must contain at least one none numerical character. Further numbers in a line are ignored. The peak positions should be always the positions of the Gaussian (see `set tail -noinclude`). The list or part of it might be preceded by a region definition: R channel_min channel_max degree_of_background_polynomial All lines following a region definition must be situated in this or further region definitions i.e. free lines must precede the first region definition. The channel number of the lines must be in ascending order. Use the command `set fit -print` to get information about errors in a peak list. The variation of a peak positions can be controlled globally with the command `set peak -nofit` or individually by setting the error on the peak position to a zero or negative value: such peak positions are kept constant. The same is true for the peak area. The width is taken from the peak list if the option `set width -list` has been set. Important note: The first data line in the list file determines the format to be read. This is important when using the `set width -list` command. Any "gaspan" data output file can be used as peak list file. This option can be disabled with the option `-search`. 3 -noappend Switches the append mode off. Default. 3 -nocommon Disables the option `-common`and is identical with the option `-individual`. Default. 3 -noefficiency Disables an efficiency calibration. See option `-efficiency`. Default. 3 -noenergy Disables an energy calibration. See option `-energy`. Default. 3 -nofit With `-nofit` specified, no variation of the peak position is done, although peaks might be added by a search of the residue (see the option `-residue`). The option `-nofit` is only legal if a peak list was defined. 3 -noinclude_background_tail If a background tail is included into the fit function it will be not included into the peak data. Default. 3 -noindividual Disables the option `-individual` and is identical with the option `-common`. 3 -nolist Disables a peak list. Equivalent with `-search`. 3 -search Peak positions are searched for by a peak searching routine. This is done by folding a zero area Gaussian with the specified width with the spectrum and looking for correlations. Default. The opposite qualifier is `-list` which allows to specify a list of peak positions. See also `-list`. 2 region Allows one to set analysing windows and/or fit regions in a spectrum. 3 -fit `set region -fit=minimum_channel,maximum_channel` Define define an analysing window in the spectrum. The default setting is from channel 1 to the last channel of the spectrum. 3 -list `set region -list=filename` Allows one to specify a file which contains a list of regions. A list of regions should be provided for spectra with high level densities. The format of this list must be: any number of comment lines R first_channel last_channel [degree_of_background_polynomial] Use the command `show limitations` to get information on the maximum number of regions and the maximum size of a region. The size of a region should be smaller than the fit region and should contain less peaks then the maximum number of peaks in a fit region. `-list` is the complement of `-search` which is equivalent to `-nolist`. 3 -nolist Disables a region list. Equivalent with `-search`. Default. 3 -search The fit regions are determined by the program. This option should not be used if the spectrum is characterised by a high level density. Default. `-search` is identical to `-nolist`. 2 statistics Allows to define statistical conditions for the fit and the output of the fit data. 3 -allpeaks With `-allpeaks` given, all peaks are accepted for output independent of their statistical meaning. In order to reject peaks with large errors use the option `-noallpeaks`. 3 -noallpeaks With `-noallpeaks` specified, peaks will be rejected in the output if the peak area is less than two times the statistical error of the area. Default. 3 -nosmooth_error The weight in calculating chi square is directly taken from the error of each channel. Default 3 -nostandard With `-nostandard` specified, it is assumed that the spectrum under consideration does not follow a Gaussian error distribution (i. e. difference spectra). An attempt will be made to estimate an average statistical significance in relation to the square root of the absolute value of the data points by looking at the variation of the data points. This option should not be used with ".daterr" files. 3 -sensitivity `set statistics -sensitivity=value` Sets the level of statistical significance in the peak search and residue search routine to either 3 times the statistical error (value=normal) or 2 times the statistical error (value=high). 3 -smooth_error The errors of the channels are smoothed - depending on the width - before calculating the weight in chi square. This technique enhances the finding of peaks with small counting rates. 3 -standard With `-standard`, the weight in calculating chi square is computed from the square root of the number of counts in each channel or from the errors specified (.daterr - format). The first one is correct with all spectra which are not manipulated. See option `-nostandard` in other cases. Default. 2 tail Allows one to specify the addition of left- and right-sided peak tails, a long ranged left-sided background tail and a step function. Tail amplitudes are defined relative to the peak height and are the same for all peaks in a fit region. By default, no tails are added to the fit (i. e. `set tail -none`). 3 -all Adds all three tails and the step function to the fit. 3 -background_tail `set tail -background_tail=range_parameter` A background tail is added to the fit function. The range parameter allows to define the variation range of the decay constant of the tail. It should be a number in the interval [0.;0.95]. The decay constant is fixed if the range parameter is 0. The default value is 0.8. Decay constant and tail amplitude are either provided internally or can be inserted with the command `set parameter -background_tail=`. The amplitude can be fixed with the command `set tail -nofit=background_tail`. The background tail can be included into the peak data with the command `set peak -include_background_tail`. See also the options `-[no]enforce_fit`. 3 -enforce_fit It does not always make sense to vary tail parameters for peaks with poor statistics, especially in gamma ray spectra. Hence the program contains a logic to decide if tail parameters are to be included into the variation of parameters. This option enforces the variation of tail parameters for all peaks. The option can be disabled with the command `set tail -noenforce_fit`. 3 -fit `set tail -fit=string` Specifies if tail amplitudes are to be varied to get the best fit. Variation of the relative amplitude extends over any positive number. The parameter string allows to select a specific tail and should be one of the strings "background", "left", "right", "step" or "all". Variation of the tail parameters can be inhibited for peaks with poor statistics. See option `-noenforce_fit`. Note that the variation of the decay constant is controlled via the range parameter which can be defined in the command `set tail -(tailkind)=range_parameter`. The default is `-fit=all`. 3 -gamma Adds a step, a background and a left peak tail to each peak. These are the most common tails in gamma-ray spectra. 3 -include The area of peak tails are always included in the area of the peaks. The inclusion of the peak tails into the position of a peak (centroid) depends on the output: - The position of the centroid is always output on screen. (option `set fit -interactive`) - The position of the Gaussian as well as the one of the centroid (if tails are defined) is always given in the file 'fithistory.gsp' (option `set fit -print`). - The position in the gaspan data summary file depends on this option: it will be the position of the centroid with the option `-include` and the one of the Gaussian otherwise (`-noinclude`). Note: The positions of the Gaussian s are needed for a peak list (see: `set peak -list=...`). The position of the peak markers in the displayed spectrum depends on the options `set display -centroid` or `set display -Gaussian` or `set display -tail_include`. The data of a background tail can be included in the peak data with the option `set peak -include_background_tail` The default option is `-include`. 3 -left_peak_tail `set tail -left_peak_tail=range_parameter` Specifies if a left tail at the peak is to be added to the fit function. The range parameter allows to define the variation range of the decay constant of the tail and should be a number in the interval [0.;0.95]. The decay constant is fixed if the range parameter is 0. The default value is 0.8. Decay constant and tail amplitude are either provided internally or can be inserted with the command `set parameter -left_peak_tail=`. The area of a peak tail is always included into the peak area, the shift in the centroid will not be taken into account if the option `set tail -noinclude` is specified. The amplitude of the tail can be fixed with the command `set tail -nofit=left_peak_tail`. The default option is `-noleft_peak_tail`. 3 -nobackground_tail Eliminates a background tail from the fit. Default. 3 -noenforce_fit It does not make sense to vary tail parameters at peaks with poor statistics, especially in gamma ray spectra. With this option the statistics in the peaks will be checked and no variation of the tail parameters will be done if the statistics is poor. Note: The input amplitude of the tails are taken into consideration when making this decision. Default. The option can be disabled with the command `set tail -enforce_fit`. 3 -nofit `set tail -nofit=string` Fixes the decay constant of the tail specified by "string" to the size specified by the command `set parameters -string=(values)`. "string" may take the values "all", "background_tail", "left_peak_tail", right_peak_tail" or "step". Consider to use this option if tail amplitudes are larger than one. 3 -noinclude The peak positions in the gaspan data summary file will be the positions of the Gaussian rather than the positions of the centroid. This is mandatory if the gaspan data summery file is to be used as a peak list file (see: `set peak -list=...`). Default option is `-include` 3 -noleft_peak_tail Eliminates a left tail to the peaks from the fit. Default. 3 -none Eliminates all tails from the fit. Default. 3 -noright_peak_tail Eliminates a right tail to the peaks from the fit. Default 3 -right_peak_tail `set tail -right_peak_tail=rangeparameter` Specifies if a right tail at the peak is to be added to the fit function. The range parameter allows to define the variation range of the decay constant of the tail and should be a number in the interval [0.;0.95]. The decay constant is fixed if the range parameter is 0. The default value is 0.8. Decay constant and tail amplitude are either provided internally or can be inserted with the command `set parameter -right_peak_tail=`. The tail amplitude can be fixed with the command `set tail -nofit=right_peak_tail`. The area of the tail is always included in the peak area. The contribution to the centroid will not be taken into account if the option `-noinclude` was specified. See also the qualifier `-[no]enforce_fit`. Default is `-noright_peak_tail`. 3 -nostep Does not include a step function into the fit function. Default. 3 -step Includes a step function for each peak into the fit function. The size of the step is relative to the peak hight and can be controlled by the options `set parameter -step=` and `set tail -nofit=step`. 2 width Sets and resets parameters concerning the width of the peaks. 3 -calibrate `set width -calibrate=filename` Gets a width calibration from the specified file. If this file is connected to a terminal (i.e. filename = tt or tty), the calibration can be typed in interactively and an output file can be generated. The data in the file should have the following structure: header lines with text followed by the data either: channel width or: channel width error or: channel error width error or: a GASPAN DATA SUMMARY file The error of the channel number is set to 0.1 if not specified, the one of the width to 0.01.The data are fitted to a polynomial of the kind fwhm = a0 + sum(i=1,n) ai*x^i with the restriction n <= 5. If n is not specified in the header of the input file with a statement "degree: n" the best degree is searched for involving a priority scheme which takes into account the normalised chi square. The user can follow this selection by setting the options `set fit -interactive` and `test print 12`. In many cases the search will end up in a high polynomial degree which is not necessarily recommendable. The graphic shows the data and the adopted fit followed by the difference between data and fit. If a filename is not specified, the width will be reset to the default value. 3 -common `set width -noindividual` There will be one common parameter for all peak width. Channel dependents of the widths of the peaks can be taken into account by either a width calibration (`set width -calibrate=...`) or by a list of peak widths (`set width -list=...`). See also `set width -individual`. 3 -individual `set width -nocommon` Each peak has its own width parameter allowing to fit a mix of different broad peaks in a fit region, for instance if there are small peaks on top of broad ones. It might be advisable to use a large range factor i.e. 80. Fitting should be done interactively (`fit min,max`) rather than in automatic mode (`go`). The opposite option is `set width -common` or `set width -noindividual`. Default. 3 -list `set width -list=filename` The option is only legal together with a peak list (`set peak -list=filename)`. The width of the peaks are taken from the width in the peak list. If the entry from this list is a negative value, the width of this peak will be taken as the absolute value and will not be varied. The value of the width is calculated from a width calibration (`set width -value=`, `set width -calibrate=` or `set parameter -width=`) if the width is zero or missing, however the first line in the peaklist must have an entry for the width in order to determine the format (see `set peak -list=`). This option can be disabled with the option `-nolist`, which is the default. 3 -nocalibrate Disables a given width calibration 3 -nolist With `-nolist`, the width of the peak is computed either by the specified value or by a width calibration. Default. 3 -range `set width -range=value` Defines the range in the width variation: the width is varied in the region (1.+/- value)*width. The width is kept constant if value is less than 0.01. Use the command `show option` to get the default value. Type a large value to see the maximum range value. 3 -value `set width -value=value` Allows the definition of a starting value for the width. Warning: This option overrides a width calibration. Default Use the command `show option` to get the default value. 1 show Displays options or current settings or shows spectrum and fit. 2 error The 4th number in the lines starting with "R" of the gaspan summary data files contains information about the fitting of that fit region. The following error indicators are or'ed together in this number: 0. No problems encountered during fit. 1. Lines too close to define a fit region: Some lines at lower channels have been dropped. Use a list of regions! 4. Fit has been stopped because of poor convergence. Result is meaningless! Control the options which control the fit function. 10. Too many lines in a fit region: The residue search had to be stopped. Use a list of regions or decrease the fit regions. 100. Input value for width too small. 400. Input value for width too large. 1000. Input value for left tail decay constant too small. 4000. Input value for left tail decay constant too large. 10000. Input value for right tail decay constant too small. 40000. Input value for right tail decay constant too large. 100000. Input value for background tail decay constant too small. 400000. Input value for background tail decay constant too large. use the `set parameter=` command in order to adjust the starting values! 2 fit Displays the spectrum and its most recent fit. In addition the residue spectrum with marks at two standard deviations will be shown. Only the fit region which falls into the analysis window set by `set region -fit` can be inspected. The display options `-on` and `-off` are ignored by this command. The display can be controlled with options given with the command `set display -option`. The current control options in proceeding are given in the keyboard window. You can return to the main command loop width CTRL-C. See also `show saved-fits`. 2 limitations Gives a printout of the restrictions to "gaspan" imposed by array sizes. 2 option Shows the currently set options on the terminal. 2 parameter Shows the coefficients of the calibrations and the parameters of the tails as far as they are defined. The current values for the width and tail parameters as obtained by the last fit or the last `show saved_fits` command are displayed, too. 2 SAMPLE The chi squares calculated by the different options `set parameter -...check` can be saved into a file with the command `test print 14` and can be viewed with this command. 2 saved_fits `show saved_fits [string]` Displays the spectrum and the fits assuming the fit parameters have been saved with the option `set fit -save`. In addition the residue spectrum with marks at two standard deviations will be shown. Only the fit regions which fall into the analysis window set by `set region -fit` can be inspected. The display options `-on` and `-off` are ignored by this command. The display can be controlled with options given with the command `set display -option`. The display will be automatically be saved if an optional string is specified. An output file with the name "stringN.eps" will be generated where N is a number incremented by one for each display starting with N = 1. The display will flush by unless the command `set display -hold` has been given. The current control options in proceeding are given in the keyboard window. You can return to the main command loop width CTRL-C. See also `show fit`. 2 spectrum `show spectrum [min,max]` Shows the part of the spectrum defined between min and max. If the optional argument is not specified, min and max are taken from the the analysing window specified by either the command `set region -fit=min,max`. The display will browse through the spectrum if the length specified by max-min+1 is greater than the size of the working spectrum (see `show limitations`) and/or browse through all spectra specified. See `help set display` for options to manipulate the display. 2 version Prints the current version of gaspan 1 test Allows to test the correct operation of the fit procedure of gaspan. 2 printout `test printout [n]` This command is mainly used for the purpose of debugging, however there are some options which are interesting for the normal user too. The program will go into a dialog if the optional number is omitted. will ignore the option, y will accept it. A number will be printed after each option and this option can be called without going into the query by adding the number to the command. Only the options which are interesting for the standard user are listed here: n = 9: display each fit step n = 10: output of the correlation spectrum (corNNNspectrumfile.dat) n = 11: output of the residue spectrum (residuexxx.dat) n = 12: print fit-sequence and fit-error when doing a calibration Please do not complain if you are using other options and don't understand the meaning of the output. 2 spectrum Generates spectra which can be analysed by gaspan. The spectra are generated with the current parameter setting of the width and the tails. Peak positions and areas as well as the background data are subject to input lead by a dialog. Gaussian error distribution is superimposed to the theoretical function.