How to use LINEID
=================

LINEID is an interactive function to identify line features in a spectrum.
It returns an IDL structure containing the identified features, on which
other functions such as CAT_ID, UPDATID, ID2EMIS2ID, etc. operate.

Below are various examples of how to use LINEID.


0. CALLING SEQUENCE
-------------------


   The most general calling sequence is

     idstr=lineid(lamda,spec,elem,wrng=wrng,wshift=wshift,locmax=locmax,$
        best=best,topX=topX,batch=batch,stor=stor,oldid=oldid,omatch=omatch,$
        n_e=n_e,logP=logP,pres=pres,dbdir=dbdir,/allah,chifil=chifil,$
        eqfile=eqfile,chidir=chidir,dem=dem,abund=abund,effar=effar,$
        wvlar=wvlar,sigmay=sigmay,xsize=xsize,ysize=ysize,wid=wid,$
        dynrng=dynrng,oxr=oxr,oyr=oyr,markp=markp,marks=marks,marko=marko,$
        /nuthin,/noday,/notime,/nouser,/nopack,stacol=stacol,stasiz=stasiz,$
        stathk=stathk)

   See the documentation for a description of the variables.


1. BATCH MODE/COMMAND LINE
--------------------------


   To simply list potential matches of a single feature on the command line,
   a la CIAO.Sherpa.GUIDE's identify() command, type:

   IDL> help,cat_id(lineid(WAVELENGTH))

   for example,

   IDL> help,cat_id(lineid(22.1))

   will read through the default line database (CHIANTI) and return with
   a default set number of possible matches (20) within a default wavelength
   range (+-0.221)

   % RD_LINE:      No line information available for H
   ..
   % RD_LINE:      No lines in this wavelength range
   .% RD_LINE:     No line information available for Li
   % RD_LINE:      No line information available for Be
   % RD_LINE:      No line information available for B
   ..
   % RD_LINE:      No lines in this wavelength range
   .............% RD_LINE:         No line information available for F
   ..
   % RD_LINE:      No lines in this wavelength range
   ...
   % RD_LINE:      No lines in this wavelength range
   ...
   % RD_LINE:      No lines in this wavelength range
   ...
   % RD_LINE:      No lines in this wavelength range
   .........
   % RD_LINE:      No lines in this wavelength range
   ...
   % RD_LINE:      No lines in this wavelength range
   ...
   % RD_LINE:      No lines in this wavelength range
   ...................% RD_LINE:   No line information available for Sc
   ..
   % RD_LINE:      No lines in this wavelength range
   .% RD_LINE:     No line information available for V
   ..
   % RD_LINE:      No lines in this wavelength range
   ...
   % RD_LINE:      No lines in this wavelength range
   .........
   % RD_LINE:      No lines in this wavelength range
   ...
   % RD_LINE:      No lines in this wavelength range
   .% RD_LINE:     No line information available for Cu
   ..
   % RD_LINE:      No lines in this wavelength range
   .
   
    WVL [Ang]       MATCH      Z ION      FLUX          +-     Tmax
   0-----------------------------------------------------1
      22.1000:    22.1012      O VII     0.17841 +-   0.000    6.30
      22.1000:    22.1020       O VI  2.0272e-06 +-   0.000    6.25
      22.1000:   -22.0970    Ca XVII  2.5012e-06 +-   0.000    6.70
      22.1000:   -22.1060     Ca XVI  5.1657e-07 +-   0.000    6.60
      22.1000:   -22.0939    Ar XVII  1.1069e-07 +-   0.000    7.30
      22.1000:    22.0931    Fe XXIV  3.9956e-08 +-   0.000    7.30
      22.1000:    22.1070    Ca XVII  3.1153e-08 +-   0.000    6.70
      22.1000:   -22.0870     Ca XVI  1.9131e-07 +-   0.000    6.60
      22.1000:    22.1140    Ca XVII  0.00064187 +-   0.000    6.70
      22.1000:    22.1174       O VI  2.9258e-14 +-   0.000    6.25
      22.1000:    22.1174       O VI  0.00064908 +-   0.000    6.20
      22.1000:    22.1200       O VI  4.7364e-15 +-   0.000    6.25
      22.1000:    22.1200       O VI  5.0908e-14 +-   0.000    6.25
      22.1000:    22.1200       O VI   0.0011296 +-   0.000    6.20
      22.1000:    22.1200       O VI  0.00010507 +-   0.000    6.20
      22.1000:    22.1210     Ca XVI  3.6417e-05 +-   0.000    6.60
      22.1000:    22.0780       O VI  3.7569e-05 +-   0.000    6.25
      22.1000:   -22.1230     Ca XVI  5.7742e-06 +-   0.000    6.60
      22.1000:    22.1230       O VI  7.2479e-06 +-   0.000    6.25
      22.1000:    22.0770       O VI  1.9083e-05 +-   0.000    6.25
   <Expression>    STRUCT    = -> <Anonymous> Array[1]

   The FLUX in this case would be in units of ph/s/cm^2, calculated
   for a flat DEM(T) or 10^14 cm^-5 over temperatures 10^4 - 10^8 K.

------------
1A. If not interested in all that informational messages, set VERBOSE=0
    for LINEID; further, to confine attention only to O lines, type:


    IDL> help,cat_id(lineid(22.1,'O',verbose=0))
    ......
     WVL [Ang]       MATCH      Z ION      FLUX          +-     Tmax
    0-----------------------------------------------------1
       22.1000:    22.1012      O VII     0.17841 +-   0.000    6.30
       22.1000:    22.1020       O VI  2.0272e-06 +-   0.000    6.25
       22.1000:    22.1174       O VI  2.9258e-14 +-   0.000    6.25
       22.1000:    22.1174       O VI  0.00064908 +-   0.000    6.20
       22.1000:    22.1200       O VI   0.0011296 +-   0.000    6.20
       22.1000:    22.1200       O VI  0.00010507 +-   0.000    6.20
       22.1000:    22.1200       O VI  4.7364e-15 +-   0.000    6.25
       22.1000:    22.1200       O VI  5.0908e-14 +-   0.000    6.25
       22.1000:    22.0780       O VI  3.7569e-05 +-   0.000    6.25
       22.1000:    22.1230       O VI  7.2479e-06 +-   0.000    6.25
       22.1000:    22.0770       O VI  1.9083e-05 +-   0.000    6.25
       22.1000:    22.1240       O VI  1.5000e-05 +-   0.000    6.25
       22.1000:    22.0440       O VI  7.0315e-12 +-   0.000    6.30
       22.1000:    22.0440       O VI  6.2800e-05 +-   0.000    6.20
       22.1000:    22.0440       O VI  6.5579e-10 +-   0.000    6.30
       22.1000:    22.0440       O VI  6.1646e-08 +-   0.000    6.20
       22.1000:    22.0415       O VI  1.2613e-07 +-   0.000    6.20
       22.1000:    22.0415       O VI  1.1724e-05 +-   0.000    6.20
       22.1000:    22.0415       O VI  1.3417e-09 +-   0.000    6.30
       22.1000:    22.0415       O VI  1.3128e-12 +-   0.000    6.30
    <Expression>    STRUCT    = -> <Anonymous> Array[1]


------------
1B. To refine the identification further, type:


    IDL> help,cat_id(lineid(22.1,'O VII',verbose=0))
    ......

     WVL [Ang]       MATCH      Z ION      FLUX          +-     Tmax
    0-----------------------------------------------------1
       22.1000:    22.1012      O VII     0.17841 +-   0.000    6.30
    <Expression>    STRUCT    = -> <Anonymous> Array[1]

    It is also possible to use "O7", "o_7", etc. to denote O VII.


------------
1C. Rather than CHIANTI, to use the SPEX database computed for a constant
    electron density of 1e10 cm^-3 instead, type:


    IDL> help,cat_id(lineid(22.1,'O7',dbdir='$SPEX',n_e=1e10,verbose=5))
    % RD_LINE: Reading from database /foo/bar/PINTofALE/emissivity/spexD

    % RD_LINE:      Working on O7
    % RD_LINE: Reading from files:
    /foo/bar/PINTofALE/emissivity/spexD/O_wvl
    /foo/bar/PINTofALE/emissivity/spexD/O_tem
    /foo/bar/PINTofALE/emissivity/spexD/O_ion
    /foo/bar/PINTofALE/emissivity/spexD/O_jon
    /foo/bar/PINTofALE/emissivity/spexD/O_src
    /foo/bar/PINTofALE/emissivity/spexD/O_10.0
    /foo/bar/PINTofALE/emissivity/spexD/O_lvl
    /foo/bar/PINTofALE/emissivity/spexD/O_ecn
    ......
    ...
    % FOLD_IONEQ: Using ion balances from: ioneq/arnaud_rothenflug.ioneq
     WVL [Ang]       MATCH      Z ION      FLUX          +-     Tmax
    0-----------------------------------------------------1
       22.1000:    22.1000      O VII  0.00013270 +-   0.000    6.40
       22.1000:    22.1000      O VII     0.13018 +-   0.000    6.30
       22.1000:    22.1000      O VII    0.043981 +-   0.000    6.40
    <Expression>    STRUCT    = -> <Anonymous> Array[1]

    where the 3 components are due to inner-shell ionization, collissional
    excitation, and radiative-recombination.


------------
1D. In order to avoid reading in the database each time, type:


    IDL> idstr=lineid(22.1,'o_7',dbdir='$SPEX',chidir=!CHIDIR,eqfile=!IONEQF,$
    n_e=1e10,verbose=0,stor=linstr)

    where the keywords CHIDIR and EQFILE point to the appropriate ion
    balance file to use.  The line database is read into the structure
    LINSTR.  This can be reused without having to specify the keywords
    DBDIR, N_E, etc.:

    IDL> help,cat_id(lineid(22.1,stor=linstr))
    Emissivities cover the range:      22.1000 -       22.1000
    current wavelength range:      21.8790 -       22.3210
    % LINEID: WARNING: input emissivities do not cover the
    % LINEID:          wavelength range of interest

     WVL [Ang]       MATCH      Z ION      FLUX          +-     Tmax
    0-----------------------------------------------------1
       22.1000:    22.1000      O VII  0.00013270 +-   0.000    6.40
       22.1000:    22.1000      O VII     0.13018 +-   0.000    6.30
       22.1000:    22.1000      O VII    0.043981 +-   0.000    6.40
    <Expression>    STRUCT    = -> <Anonymous> Array[1]

    (in this case, the warning is irrelevant; ignore it)
    the details of each line can be summarized with:

    IDL> help,cat_ln(linstr,/comm)
         Z ION  WVL [Ang]      FLUX     Tmax
    0---------------------------------------------1
         O VII   22.1000  0.00013270  6.400   HE6      (II) -> 
    1---------------------------------------------2
         O VII   22.1000     0.13018  6.300   HE6      (EX) -> 
    2---------------------------------------------3
         O VII   22.1000    0.043981  6.400   HE6      (Recomb) -> 
    <Expression>    STRUCT    = -> <Anonymous> Array[1]


------------
1E. Multiple features may also be identified in batch mode.  The keyword
    BATCH must be used in this case.  If the keyword BEST is also used,
    the program makes an informed decision based on the strength of the
    match as well as the nearness to the feature.


    IDL> help,cat_id(lineid([19.0,22.1],'O',/batch,/best))
    ......

     WVL [Ang]       MATCH      Z ION      FLUX          +-     Tmax
    0-----------------------------------------------------1
       19.0000:    18.9671     O VIII     0.27836 +-   0.000    6.50
    1-----------------------------------------------------2
       22.1000:    22.1012      O VII     0.17841 +-   0.000    6.30
    <Expression>    STRUCT    = -> <Anonymous> Array[1]


2. INTERACTIVE MODE
-------------------


   If a spectrum is available as an array as a function of a wavelength
   array, then multiple line features may be identified interactively.

   Here is an example walk-through, using an observed Chandra HETG/MEG
   (+1 order) spectrum of the RSCVn binary HR1099.

   IDL> .run initale
   IDL> restore,!ARDB+'/demo_v711Tau.save'
   IDL> help,name='*_[MV][17][P1]*'
   DEM_V711TAU     DOUBLE    = Array[81]
   EFFAR_M1P       FLOAT     = Array[8200]
   EXPTIM_V711TAU  FLOAT     =       136620.
   LAM_M1P_V711TAU DOUBLE    = Array[8192]
   LOGT_V711TAU    FLOAT     = Array[81]
   SPC_M1P_V711TAU INT       = Array[8192]
   SPE_M1P_V711TAU FLOAT     = Array[8192]
   WVLAR_M1P       FLOAT     = Array[8200]
   WW_M1P_V711TAU  DOUBLE    = Array[8193]

   Here, SPC_M1P_V711TAU(LAM_M1P_V711TAU) are the observed counts
   spectrum as a function of wavelength (WW_M1P_V711TAU are the
   wavelength bin-boundaries);
   SPE_M1P_V711TAU(LAM_M1P_V711TAU) are the Gehrel's approximation
   to Poisson error on the counts;
   DEM_V711TAU(LOGT_V711TAU) is an EUVE-based approximate Differential
   Emission Measure distribution as a function of log(Temperature);
   EFFAR_M1P(WVLAR_M1P) is the effective area as a function of
   wavelength; and
   EXPTIM_V711TAU is the exposure time for the observation.

   Plot each of the above, for example, thusly:-
   * The counts spectrum and errors
     plot,LAM_M1P_V711TAU,SPC_M1P_V711TAU,psym=10,xtitle='Wavelength ['+$
     string(byte(197))+']',ytitle='Counts/bin',title='HR 1099: HETG/MEG +1',$
     xrange=[5.,20.],yr=[0.1,1200],/ys
     for i=0L,n_elements(LAM_M1P_V711TAU)-1L do oplot,$
     LAM_M1P_V711TAU[i]*[1,1],SPC_M1P_V711TAU[i]+SPE_M1P_V711TAU[i]*[-1,1],$
     color=1 & setcolor,'red',1
   * The effective area
     plot,WVLAR_M1P,EFFAR_M1P,xtitle='Wavelength ['+string(byte(197))+']',$
     ytitle='Effective Area [cm!u2!n]',title='HETG/MEG +1',xr=[5.,20.]
   * The normalized spectrum
     tmp_effar=interpol(EFFAR_M1P,WVLAR_M1P,LAM_M1P_V711TAU)
     plot,LAM_M1P_V711TAU,SPC_M1P_V711TAU/tmp_effar/EXPTIM_V711TAU,$
     psym=10,xtitle='Wavelength ['+string(byte(197))+']',$
     ytitle='Counts cm!u-2!n s!u-1!n]',title='HR 1099: HETG/MEG +1',$
     xr=[5.,20.]
   * The DEM
     plot,LOGT_V711TAU,DEM_V711TAU,psym=10,/ylog,xtitle='log!d10!n (T [K])',$
     ytitle='DEM [cm!u-5!n]',title='EUVE based approximate DEM for HR1099'
     
   Note that if the DEM is not defined on the same temperature grid as the
   emissivities, then it should be interpolated.  For example:
     oT=lindgen(21)*4 & tmp_LOGT=LOGT_V711TAU[oT] & tmp_DEM=DEM_V711TAU[oT]
     oplot,tmp_LOGT,tmp_DEM,psym=10,color=2 & setcolor,'yellow',2
     correct_logT=findgen(81)*0.05+4.
     new_DEM = mk_dem('interpolate',logT=correct_logT,$
       indem=tmp_DEM,pardem=tmp_LOGT)
     oplot,correct_logT,new_DEM,psym=10,color=3 & setcolor,'green',3

   In this case, an appropriate calling sequence would be:

   IDL> idstr=lineid(LAM_M1P_V711TAU,SPC_M1P_V711TAU,stor=stor_2,$
   n_e=!EDENS,dbdir=!LDBDIR,chifil=1,eqfile=!IONEQF,chidir=!CHIDIR,$
   DEM=DEM_V711TAU*EXPTIM_V711TAU,abund=!ABUND,$
   effar=EFFAR_M1P,wvlar=WVLAR_M1P,verbose=!VERBOSE)

   after writing a lot of informational messages (saying what element
   it is reading, etc.), the spectrum is plotted in a window and the
   user is invited to select a feature for identification.  The selection
   is handled by the procedure PICKRANGE, which is described in detail
   elsewhere.  For here, briefly note the following characteristics:

   1. Select an area on the spectrum to zoom into using the right mouse
      button -- hold down and drag, say from (18,250) to (21,0).  The
      numbers do not have to be precise.
   2. Zoom into the selected area by clicking on the left button.
      (NOTE: clicking the middle mouse button will "unzoom" the plot;
      clicking on the right mouse button will pass control to the
      keyboard, which allows "scrolling" the plot window)
   3. Select the line feature for identification using the left
      mouse button -- hold down and drag from approximately (18.5,150)
      to (19.5,150).  This largest local maximum in the selected range
      will be the candidate for identification.
   4. exit the interactive feature selection with a click (NO drag!)
      of the right mouse button.

   At this point, a widget listing a number of matches will pop up.
   Select the best match(es) by clicking on the box in the left-most
   column.  The candidate matches may also be sorted by other means,
   for example, by intensity (SORT->byIntensity), and the likely ID
   for this feature, O VIII 18.967, will rise to the top of the list.
   Click on the box at the left to select it as the ID.

   Click on NEXT to continue with interactive feature identification,
   or click on QUIT to exit LINEID.

   IDL> help,cat_id(idstr)
    WVL [Ang]       MATCH      Z ION      FLUX          +-     Tmax
   0-----------------------------------------------------1
      18.9825:    18.9671     O VIII      357.54 +-   0.000    6.50
   <Expression>    STRUCT    = -> <Anonymous> Array[1]


------------
2A. It is possible to edit existing ID structures interactively.  An
    existing set of IDs may be passed into LINEID using the keyword
    OLDID, and the manner of editing is controlled by the keyword
    OMATCH.  For example, if you have spectra from different instruments
    of the same source, and have a set of IDs derived using one spectrum,
    you can use a value of OMATCH = -ve relative wavelength error to
    avoid IDing the same features multiple times.