
NAME
  
    specmeasure -- fit line profiles to peaks in
	one-dimensional grating data using ascfit.

USAGE

    specmeasure [data_file] [num_cols] [flux_corrected] 
        [peaks_file] [cont_file] [nocont_file]
	[output_file1] [output_file2] [model] [fit_region]
	[grating] [max_fwhm] [min_fwhm] [max_continuum_slope]
        [use_ascfitlib=] [ascfit_method=] [ascfit_stats=]
        [ascfit_confidence=] [log_file1=] [log_file2=] [clobber=]
        [debug]

DESCRIPTION

    This program fits line profiles to detected peaks
    using the information in the peaks file created by 
    line_detect_features as initial guesses for fitting parameters.
    Fitting is done using ascfit in one of 2 modes: 1) the tool
    can either write an ascii script file which can be run by ascfit,
    producing log files and command line scripts; 2) or the tool can 
    call the ascfit library directly, without creating the ascfit
    command line files with logs.  Both methods give the same output
    fit results. Constraints on best fit parameters are set according
    to user input.  

    There are currently three fitting models: gauss, lorentz and 
    xspec gauss.  The fitting done to data which is not continuum-subtracted
    uses two models; one of the above profiles + linear
    continuum.  There are no user parameters to modify the
    polynomial continuum fitting (yet).  The input guess fitting parameters
    for the linear continuum come from the input file of
    line positions, continuum amplitudes and continuum slope guesses.
    The continuum polynomial function for a given interval is 
    fcn(w) = a * w + b.  Fitting to continuum-subtracted data 
    (root_nocont.dat) uses only the selected profile function.

    The output files are ascii tables containing the 
    best fit parameters;  the input peaks file with a continumm and
    the input data file without a continuum both have fit results.

PARAMETERS

    input_data_file [filename]  (root.dat)

        Input ascii data file containing 3 or 4 columns: wavelength, 
        wavelength bin width, counts or flux, and counts_error or 
        flux_error.  The optional column is the wavelength bin width;
        if this column is not provided, then the bin width is calculated
        using the wavelngth positions in the list, assuming no gaps in
        the data.  The data columns are: col1=position, col2=optional 
        bin width;  if bin width present: col3=counts or flux,
        col4=counts_err or flux_err;  if bin width not present: 
        col2=counts or flux, col3=counts_err or flux_err. 
 
        Sample file with 3 columns:

          lam       counts    counts_err

        1.448900      1	        1.0
        1.460100      1	        1.0
        1.471200      2         1.41
        1.482300      3         1.73
        1.493400      3         1.73
        1.504600      3         1.73
        1.515700      2         1.41
        1.526800      1         1.0
        1.537900      0         0
        1.549000      0         0

        Sample file with 4 columns:

          lam       lam_wid   counts	counts_err

        1.448900    0.011200      1	    1.0
        1.460100    0.011100      1	    1.0
        1.471200    0.011100      2         1.41
        1.482300    0.011100      3         1.73
        1.493400    0.011200      3         1.73
        1.504600    0.011100      3         1.73
        1.515700    0.011100      2         1.41
        1.526800    0.011100      1         1.0
        1.537900    0.011100      0         0
        1.549000    0.011200      0         0

        The data file must end with ".dat" since ascfit reads only
        the format for now.

    num_cols_in_data = "3" [int: 3 or 4]
   
        The input data file contains either 3 or 4 columns of info.

    flux_corrected = no  [boolean]
   
        Is the input file flux corrected?  This parameter is currently
        not being used.

    peaks_file = "." [filename (root.peaks)]

	File containing peak information, usually created by the
	line_detect_features program.  

	"." creates a peaks file name from the data file name by
	adding a '.peaks' extension, e.g. if data_file = "foo.dat"
	then the program will look in the current directory for a file
	called "foo.peaks".   	

	Contains 7 ascii columns: peak number, amplitude (counts),
	continuum (counts), continumm slope, fwhm, position (Amgstroms),
        and position bin width (A), e.g.

        #
        # data file: foo.dat
        # minimum amplitude emission: 40.0
        # minimum amplitude absoption: 100.0
        # peaks: 13
        #
        # peak ampl   cont   cont_slope   fwhm        pos     pos_bin_wid 
        # ---------------------------------------------------------------
          1   215.00 42.792  1.357e-02   3.340e-02   6.176100   0.011100    
          2   121.00 67.515 -1.591e-01   3.340e-02   7.166000   0.011200    
          3   138.00 57.324  2.119e-02   4.450e-02   7.989100   0.011100    
          4   161.00 62.520 -8.944e-02   4.450e-02   8.311700   0.011100    

	Comment lines begin with '#' and are ignored by the program.

    cont_file = "." [filename]  (root_cont.dat)

	Input file for the continuum of the data set (usually produced
        by the line_detect_features tool).  This file
        contains four columns of information: wavelength, 
        wavelength bin width, continuum counts and continuum counts 
        error.  The file is the
        same length as the input data file, with the same wavelength
        range and step sizes.  

	"." indicates that the root name of the cont_file is dependant
        on the 'data_file' name, e.g., if data_file = "file.dat", then
        cont_file = "file_cont.dat".  

    nocont_file = "." [filename]   (root_nocont.dat)

	Input file for the (data-continuum) information (usually produced
        by the line_detect_features tool).  This file
        contains four columns of information: wavelength, wavelength
        bin width, counts=(data-continumm) and counts_error=
        sqrt(data_error^2 + continuum_error^2).  The file is the
        same length as the input data file, with the same wavelength
        range and step sizes.  

	"." indicates that the root name of the nocont_file is dependant
        on the 'data_file' name, e.g., if data_file = "file.dat", then
        nocont_file = "file_nocont.dat".  

    output_file1 = "." [filename]  (root.fit1)

	Output file name, for the fit results of the data WITH 
        continuum.

	"." creates an output file name based on the input data file
	name by adding a '.fit1' extension, e.g., if data_file =
	"foo.dat", then output_file = "foo.fit1".

    output_file2 = "." [filename]  (root.fit2)

	Output file name, for the fit results of the data WITHOUT 
        continuum.

	"." creates an output file name based on the input data file
	name by adding a '.fit2' extension, e.g., if data_file =
	"foo.dat", then output_file = "foo.fit2".

    model = "gauss" [gauss|xsgauss|lorentz|lorentzInt]

	Type of line profile to fit.  Currently three choices.
        The model used for the continumm fitting is currently a 
        polynomial 1D;  there is no choice to change this (currently).

    fit_region = 2.0 [floating point]

	For each line, limit the fit to data points between initial
	position (energy) +/- fwhm times this factor.  Fit region 
        (line_center +/- (fit_region * fwhm_max))

    grating = HEG [HEG|heg|MEG|meg|LEG|leg]
	
	Grating associated with the input data.  While the data is
        in ascii format, the tool needs to know the grating used to
        create the dataset.  This parameter will go away with the use
        of FITS i/o.

    max_fwhm = 4.0 [floating point]
	
	Set the maximum fwhm to the line spread funciton (assumes
        wavelength) times this factor.  Max allowed fwhm = 
        (LSF * max_fwhm).  This parameter sets the 
        limits of the best fit values determined by ascfit. The
        LSF is derived from the resolving power data plotted in the 
        proposer's guide.

        Line Spread Function width
	LSF_WIDTH = (1.695e-2) * (wavelength ** -0.1120)      heg
                  = (3.124e-2) * (wavelength ** -0.1689)      meg
                  = (5.299e-2) * (wavelength ** -0.0918)      leg

	where wavelength = photon position in Angstroms.

    min_fwhm = 0.25 [floating point]
	
	Set the minimum fwhm to the line spread funciton (assumes
        wavelength) times this factor.  Min allowed fwhm = 
        (LSF * min_fwhm).  This parameter sets the 
        limits of the best fit values determined by ascfit. The
        LSF computation details are listed in the min_fwhm parameter.

    max_continuum_slope = 0.01 [floating point]

        Max allowed fractional change in the continuum across a given 
        fit region.  If the fit region lies between lambda_lo and 
        lambda_hi and the continuum function evaluated at the center of
        the fit region is C(lambda_mid).  The best fit continuum slope
        satisfies:

        fabs(slope) <=  max_continuum_slope * C(lambda_mid) / 
                         (lambda_hi - lambda_mid)

        Steeper slopes arent allowed.  If max_continuum_slope = 0.1, 
        then the linear continuum function should be flat enough so 
        that the continuum at either edge of the fit region should be
        within 10% of the value at the center.

    (use_ascfitlib = "no") [boolean: yes or no]

	The switch to use the ascfit library calls or the ascii
        script to execute ascfit.  (The resultant fits are identical,
        but the non-lib methods produces script file and log files
        of the interactive fitting.)

    (ascfit_method = "simplex") [string: grid|grid-powell|levenberg-
                                 marquardt|montecarlo|monte-powell|
                                 powell|simplex|simul-ann-1|simul-ann-2|
                                 simul-pow-1|simul-pow-2]

	Use this ascfit fitting method.

    (ascfit_stats = "chi parent") [string: chi gaussian|chi parent|
                                   chi gehrel|cash|likelihood|userstat]

	Use this ascfit fitting statistical method.  Since the data
        contains zero and negative counts (data-cont file), some of
        the stat methods will fail.  Please be careful when setting
        this parameter; 'chi parent' works with data which may have
        0 and negative counts.

    (ascfit_confidence = 68.3) [real: 68.3,68.3|90.0|99.0]

        Confidence level for delta chi squared fitting.  
 
    (log_file1 = ".") [filename (root.log1)]

	In this file, save what would normally appear on the screen
	when running ascfit using scripts (non-lib).
	
	"" or "NONE" discards ascfit screen output.
	
	"." creates a log file name from the input data file name by
	adding a '.log1' extension, e.g., if data_file = "foo.dat" then
	log_file = "foo.log1".

    (log_file2 = ".") [filename (root.log2)]

	In this file, save what would normally appear on the screen
	when running ascfit using ascfitlib (non-script).
	
	"" or "NONE" discards ascfit screen output.
	
	"." creates a log file name from the input data file name by
	adding a '.log2' extension, e.g., if data_file = "foo.dat" then
	log_file = "foo.log2".

    (clobber = no) [boolean: yes or no]

	Overwrite output_file and log_file if they exist.

    (display = 1) [integer (0:1)]
	
	How much output you want to see on your screen while
	specmeasure is running.  0 means work silently.

    (mode = "ql") [string]
	
	Parameter interface mode.  "ql" stands for "query and learn"  
	which prompts you for input and updates
	"specmeasure.par" with your responses. 

EXAMPLE

    Fit a gaussian line profile to each of the peaks found in
    "foo.dat".  "foo.peaks" contains output from the
    line_detect_features program , along with "foo_cont.dat"
    and "foo_nocont.dat". 

    > pset specmeasure 
    input data file (must end in '.dat') (): foo.dat
    num of column in input data file (3:4) (3): 
    Is the input file flux corrected? (no):
    input peaks file [root.peaks] (.): 
    input peaks file [root_cont.dat] (.): 
    input peaks file [root_nocont.dat] (.): 
    output best fit params, data w/cont [root.fit1] (.): 
    output best fit params, data w/o cont [root.fit2] (.): 
    line profile type (gauss|xsgauss|lorentz|lorentzInt) (gauss): 
    limit fit region to fwhm times this factor (0) (2.0): 
    Grating associated with the input data (HEG|heg|MEG|meg|LEG|leg) (HEG):
    set max fwhm to position times this factor (0) (0.01): 
    Use ascfit library (yes or no), else use script with logs (no): yes
    ascfit method: powell, simplex, grid ... (grid|grid-powell|
      levenberg-marquardt|montecarlo|monte-powell|powell|simplex|
      simul-ann-1|simul-ann-2|simul-pow-1|simul-pow-2) (simplex): 
    ascfit stats: chi gaussian, chi gehrel, chi parent, cash, 
      likelihood ... (chi gaussian|chi parent|chi gehrel|cash| 
      likelihood|userstat) (chi parent): 
    Confidence level for delta chi squared (68.3|90.0|99.0) (68.3): 
    ascfit log file 1 [root.log1] (.): 
    ascfit log file 2 [root.log2] (.): 
    OK to overwrite existing output and log files? (yes): 
    display level (0 = no display) (0:1) (1): 
    mode (ql): 

    > specmeasure 


    These ascii .fit# files contain the results;  the columns are:

        #
        # data file: foo.dat
        # minimum amplitude: continuum level
        # peaks: 16
        # model: gauss
        # fit region: +/- 2.0 * fwhm
        # amplitude range: +/- 100.0 % of initial guess
        # position range: (line_center +/- (2.0 * fwhm_max))
        # max fwhm: (line_spread_function * 4.0)
        # min fwhm: (line_spread_function * 0.25)
        #
        #    |       BEST FIT RESULTS w/ CONTINUUM

        peak |  ampl        ampl_min    ampl_max    
                cont_ampl   cont_slope  cont_pos    
                fwhm        fwhm_min    fwhm_max    
                pos         pos_min     pos_max     



DATE

    05/14/98

