
NAME
  
    specidentify -- identify features in grating spectrum  

USAGE

    specidentify [features_file] [line_list] [output_file] 
        [doppler_shift_unit=] [source_doppler_shift=] 
        [tolerance=] [source_temp_unit=] [source_temp=] 
        [source_density=] [filter_string=] [clobber=] [debug=]   

DESCRIPTION

    This program uses the information from the fitted peaks file created
    by line_measure_features to try to correlate the list of observed
    lines with the database line list to produce
    the greatest number of matches within the allowed 
    wavelength error tolerance.  It    
    compiles a list of the matched lines and ions; the matched list
    is also filtered using the user defined source temperature and the user
    defined source redshift.

PARAMETERS

    features_file [filename]

	Input data file name; this file is the output of the 
        line_measure_features tool.  The file typically ends in .fit#;
        where .fit1 is the with on the data with continuum and the
        .fit2 is the fit on the data which has had the continuum
        subtracted.  These ascii .fit# files contain the following columns:

        #
        # data file: marx_zoo2.dat
        # minimum amplitude: continuum level
        # peaks: 13
        # model: gauss
        # fit region: +/- 2.0 * fwhm
        # amplitude range: +/- 100.0 % of initial guess
        # position range: +/- 100.0 % of initial guess
        # max fwhm: E * 1.0e-02
        #
        #    |       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     

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

    line_list = [filename]

	Ascii file containing the database of emission line wavelengths.
        The current format of this file is:

             id number in master list.
             element id = Fe, Si, S, etc.
             ion id = by roman numeral 
             transition type = defined in e.g. Mewe and Gronenschild, 1981,
                      A&A Supp., 45, 11.
             wavelength = Angstrom
             energy = keV
             list of line strength values at 40 temperatures. (log Kelvin)

        Example 2 lines, from the current list:

        Nr  ion      Transit.   E\(eV\) Lambda\(A\)  4.0  4.1  4.2  
        4.3  4.4  4.5  4.6  4.7  4.8  4.9  5.0  5.1  5.2  5.3  5.4  
        5.5  5.6  5.7  5.8  5.9  6.0  6.1  6.2  6.3  6.4  6.5  6.6  
        6.7  6.8  6.9  7.0  7.1  7.2  7.3  7.4  7.5  7.6  7.7  7.8  
        7.9  8.0 

        1658 Fe IX     A8B         6.327 1959.600   0.00     0.00     
        0.00     0.00     0.00     0.00     0.00     0.00     0.00
        0.00     0.00     0.00     0.00   8.97 7.42 6.41 5.83 5.54 
        5.43 5.49 5.80 6.50 7.63 9.21   0.00     0.00     0.00     
        0.00     0.00     0.00     0.00     0.00     0.00     0.00
        0.00     0.00     0.00     0.00     0.00     0.00     0.00  


    output_file = "." [filename] (root.out)

	Output file name.

        "." creates an output file name based on the input data file
        name, e.g., if features_file = "file.fit", then output_file =
        "file.out".  

    (doppler_shift_unit = "redshift") [redshift|km/s]

	The units of source_doppler_shift.  

    (source_doppler_shift = 0)

	The Doppler shift of the source.  The value should be set
        according to the units set in the 'doppler_shift_unit'
        parameter.  The Doppler shift is used to shift the wavelengths
        of the observed spectral peaks to the 'rest' wavelength; the
        rest wavelength is used to match the lines in the data base.
        The relativistic Doppler shift formula is used:

                delta_lam = lam_observed - lam_rest

                z = delta_lam/lam_rest = 
                    (sqrt((1+v/c)/(1-v/c))) - 1)

                C = 2.99792458E5 km/s

    (tolerance = 0)

        Maximum allowed fractional error in line position. For example,
        suppose the measured confidence limits on the line are 
        (c1,c2) with the best position at "c" and suppose the line 
        database lists confidence limits (d1,d2) on the line position
        with the tabulated position at "d".  A line is accepted as
        a candidate identification if 

                   1)  (d1,d2) overlaps (c1,c2)   OR
                   2)  if abs(c-d) < tolerance * (c+d)/2 

    (temp_unit = "Kelvin") [Kelvin|keV]

	The units of source_temp.

    (source_temp = 1E4)  [1E4 -> 1E8 Kelvins] [1E11  -> 1E15 keV]

	Estimated source temperature in units of temp_units.  The 
        temperature is used to filter the list of candidate identifications
        for spectral features.  Only lines present in collisional
        ionization equilibrium at this temperature
        are retained in the identification list.

    (source_density = 0)  [cm^-3]

	The ion number density.  (Currently not being used
        as a filter parameter).

    (filter_string = "")  [comma separated list]

        This is a list of elements and/or ions to include or exclude
        from the line identification search.  Elements are specified
        by their 2 letter chemical symbol ("Fe", "Si"), ions are
        specified by the chemical symbol and ion charge ("Fe 0" is
        neutral iron, "Fe 25" is hydrogenic, "Fe 24" is He-like,
        etc.).  If the filter string is empty or blank, all elements
        and ions in the database are included in the search.  If specific
        elements and ions are listed, only those listed are included
        in the search.  Specific elements or ions can be excluded from
        the search by prefixing the name with a tilde character ("~Fe"
        would excluded all iron ions from the search, "~Fe 17" would
        exclude only Fe XVIII).   If inclusive and exclusive filtering
        is combined, all excluded elements/ions must appear before
        the inclusive names:  if including all iron ions except Fe +15,
        the string should read "~Fe 15, Fe")

        EXAMPLE 1: 
        	include Mg 7
        	include Mg 14
        	exclude Fe 23
        	include all the rest of the ions of Fe
        
        	filter_string = "Mg 7, Mg 14, ~Fe 23, Fe"

        EXAMPLE 2:
        	exclude Mg
        	exclude Si
        	exclude Fe 23
         
                filter_string = "~Mg, ~Si, ~Fe 23"
                includes all elements and ions in the 
                line list, except Magnesium, Silicon and Fe +23.

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

	Overwrite output_file if they exist.

    (display = 1) [0 = no debugging info, 5 = max debugging info]
	
	Controls the amount of output on your screen while
	specidentify 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
	"specidentify.par" with your responses. 

EXAMPLE

    Find all the matched lines and ions to the fitted peaks found in
    "marx_zoo.fit1".  This file was generated by line_measure_features
    which fit gaussian peaks to the output from the line_detect_features
    program. 

    >) pset specidentify 
    Input data file with line features & stats (): marx_zoo.fit1
    Database line list for identifications (): Spex_Lines.txt
    Output identified peaks file (): marx_zoo.out1
    Source Doppler shift units (for below) (redshift|km/s) (redshift): 
    Source redshift (0): 
    Allowable tolerance in line position error (0):
    Source temperature units (for below) (Kelvin|keV) (Kelvin):
    Source temperature (Kelvins) (10000) (): 10000000
    Source density (0): 
    OK to overwrite existing output file? (no): yes
    Display level (0 = no display) (0:5) (0):
    mode (ql): 

    > specidentify 
    Input data file with line features & stats (marx_zoo.fit1): 
    Database line list for identifications (Spex_Lines.txt): 
    Output identified peaks file (marx_zoo.out1): 
 
    > cat marx_zoo.out1

----------------------------------------------------------------------

			 VALUE	      VALUE_MIN	   VALUE_MAX
			 -----	      ---------	   ---------
Peak #1: CONT		 53.922      
	: AMPL		 160.454      153.703      167.100     	
	: FWHM		 2.862e-02    2.708e-02    3.016e-02   
	: POS_OBSERVED	 6.180        6.180        6.181       	
	: POS_REST	 6.180        6.180        6.181       	
	--------------------------------------------------------------
Matched  lam_rest     strength     ID	 elem	     ion       label
-------  --------     --------     --	 ----	     ---       -----
	 6.180        3.631e-21    956     si        xiv       h1a      
	 6.180        7.943e-19    943     si        xiii      hes4     
	 6.180        1.122e-18    942     si        xiii      hes3     
----------------------------------------------------------------------

			 VALUE	      VALUE_MIN	   VALUE_MAX
			 -----	      ---------	   ---------
Peak #2: CONT		 82.996      
	: AMPL		 241.998      67.515       242.000     	
	: FWHM		 4.778e-07    1.000e-09    1.042e-04   
	: POS_OBSERVED	 7.099        7.099        7.199       	
	: POS_REST	 7.099        7.099        7.199       	
	--------------------------------------------------------------
Matched  lam_rest     strength     ID	 elem	     ion       label
-------  --------     --------     --	 ----	     ---       -----
	 7.176        1.023e-19    742     al        xiii      h1b      
	 7.171        6.310e-20    741     al        xiii      h1a      
	 7.171        2.042e-17    735     al        xii       hes4     
	 7.171        2.951e-17    734     al        xii       hes3     
	 7.169        1.820e-19    4891    fe        xxiv      li01017  
	 7.169        6.918e-18    4636    fe        xxiii     li01017* 
	 7.165        9.333e-20    4890    fe        xxiv      li01018  
	 7.165        3.631e-18    4635    fe        xxiii     li01018* 
	 7.110        4.365e-19    5385    ni        xxvi      li4      
	 7.110        3.890e-18    5362    ni        xxv       li4*     
	 7.100        3.631e-20    700     mg        xii       h2       
	 7.100        1.479e-17    683     mg        xi        h2*      
----------------------------------------------------------------------

			 VALUE	      VALUE_MIN	   VALUE_MAX
			 -----	      ---------	   ---------
Peak #3: CONT		 61.440      
	: AMPL		 81.070       75.388       86.590      	
	: FWHM		 3.466e-02    3.194e-02    3.890e-02   
	: POS_OBSERVED	 7.987        7.986        7.989       	
	: POS_REST	 7.987        7.986        7.989       	
	--------------------------------------------------------------
Matched  lam_rest     strength     ID	 elem	     ion       label
-------  --------     --------     --	 ----	     ---       -----
	 7.986        4.677e-20    4897    fe        xxiv      li01011  
	 7.986        1.622e-18    4649    fe        xxiii     li01011* 
----------------------------------------------------------------------

			 VALUE	      VALUE_MIN	   VALUE_MAX
			 -----	      ---------	   ---------
Peak #5: CONT		 65.878      
	: AMPL		 134.038      126.552      141.553     	
	: FWHM		 2.486e-02    2.319e-02    2.658e-02   
	: POS_OBSERVED	 8.420        8.419        8.421       	
	: POS_REST	 8.420        8.419        8.421       	
	--------------------------------------------------------------
Matched  lam_rest     strength     ID	 elem	     ion       label
-------  --------     --------     --	 ----	     ---       -----
	 8.420        3.631e-18    688     mg        xi        hes4     
	 8.420        5.495e-18    687     mg        xi        hes3     
----------------------------------------------------------------------

			 VALUE	      VALUE_MIN	   VALUE_MAX
			 -----	      ---------	   ---------
Peak #7: CONT		 31.934      
	: AMPL		 152.000      16.920       152.000     	
	: FWHM		 1.000e-09    1.000e-09    1.958e-03   
	: POS_OBSERVED	 10.727       10.659       10.727      	
	: POS_REST	 10.727       10.659       10.727      	
	--------------------------------------------------------------
Matched  lam_rest     strength     ID	 elem	     ion       label
-------  --------     --------     --	 ----	     ---       -----
	 10.710       7.586e-17    4706    fe        xxiii     be59241  
	 10.682       1.349e-16    4705    fe        xxiii     be15184  
	 10.679       1.047e-16    4704    fe        xxiii     be59254  
	 10.676       4.786e-17    4703    fe        xxiii     be01022  
	 10.674       8.710e-17    4702    fe        xxiii     be55244  
	 10.663       2.455e-20    4908    fe        xxiv      li01005  
	 10.663       1.096e-18    4701    fe        xxiii     li01005* 
----------------------------------------------------------------------

			 VALUE	      VALUE_MIN	   VALUE_MAX
			 -----	      ---------	   ---------
Peak #10: CONT		 14.233      
	: AMPL		 85.114       80.921       89.316      	
	: FWHM		 2.667e-02    2.513e-02    2.826e-02   
	: POS_OBSERVED	 11.178       11.177       11.178      	
	: POS_REST	 11.178       11.177       11.178      	
	--------------------------------------------------------------
Matched  lam_rest     strength     ID	 elem	     ion       label
-------  --------     --------     --	 ----	     ---       -----
	 11.178       1.023e-20    4910    fe        xxiv      li03008  
	 11.177       4.677e-17    4739    fe        xxiii     be25184  
----------------------------------------------------------------------

			 VALUE	      VALUE_MIN	   VALUE_MAX
			 -----	      ---------	   ---------
Peak #12: CONT		 12.779      
	: AMPL		 87.784       83.543       92.014      	
	: FWHM		 2.479e-02    2.323e-02    2.642e-02   
	: POS_OBSERVED	 11.760       11.760       11.761      	
	: POS_REST	 11.760       11.760       11.761      	
	--------------------------------------------------------------
Matched  lam_rest     strength     ID	 elem	     ion       label
-------  --------     --------     --	 ----	     ---       -----
	 11.761       1.202e-19    4793    fe        xxiii     be05020  
----------------------------------------------------------------------

			 VALUE	      VALUE_MIN	   VALUE_MAX
			 -----	      ---------	   ---------
Peak #13: CONT		 14.550      
	: AMPL		 41.474       36.364       46.607      	
	: FWHM		 1.000e-09    1.000e-09    1.632e-02   
	: POS_OBSERVED	 12.138       12.138       12.138      	
	: POS_REST	 12.138       12.138       12.138      	
	--------------------------------------------------------------
Matched  lam_rest     strength     ID	 elem	     ion       label
-------  --------     --------     --	 ----	     ---       -----
	 12.138       9.120e-21    420     ne        x         h1b      




DATE

    11/18/97

