SMART Manual Source Finder

Note :

The Manual Source Finder is designed for IRS Low Resolution data where the slit is wider than the point spread function (psf). While IRS High Resolution data can be extracted with the Manual Source Finder it is best extracted using full aperture extraction.

The SMART Manual Source Finder is invoked by selecting the "Manual Source Finder - Extraction" and "Extract" options on the SMART "Extraction" window. (See Spectral Extraction Types.) This displays the "SMART Manual Source Finder" window :

To use the Manual Source Finder :

1. Select data :
   Select a data set for processing from the "Select BCD" drop down menu. This lists all BCDs selected for extraction from the current dataset. (Highlighted in the Dataset Manager.) Once a file is selected file properties from the FITS header are displayed in the top right hand corner box :
   • BCD Data (Object name, RA and DEC.)
   • FOVNAME
   • FOVID (For list see FOVID Values.)
   • APERNAME

   The spectral image will then appear in the central display box and a list of orders (with their wavelength ranges) will be displayed to its right.

2. Adjust the display:
   • The "Lower Level" and "Upper Level" boxes can be used to set a range of intensity. The default is the maximum possible range for the selected spectra.
     • Note : It is necessary to press "Enter" (Return) on your keyboard while the cursor is in each box for a value to register.
     • Click on the "Display" button to display the results of changing intensity in the upper display box.

   • Clicking the "Hist Equal" button performs a Histogram Equalization of the current data. The results are displayed in the upper display box.
   • Note : This uses the IDL provided "HIST_EQUAL" function. From the IDL help text :

     The HIST_EQUAL function returns a histogram-equalized byte array.

     The HISTOGRAM function is used to obtain the density distribution of the input array. The histogram is integrated to obtain the cumulative density-probability function and finally the lookup function is used to transform to the output image.

     Note - The first element of the histogram is always zeroed to remove the background. (This description copyright Research Systems Inc.)

3. Select an order for processing :
   • Click on the relevant "order" button. In the illustration above the 2nd order of a Short-Low spectrum is selected.
   • A plot of average intensity against cross dispersion distance (in pixels) is shown in the cross-dispersion display box. The plot title is :
     • "Co-Added" followed by the module prefix, one of SH, LH, SL or LL.
     • "Order#"
     • "All Rows"
     • "Lambda : - wavelength range in microns".
   • Initially this will be constructed using with the default options :
     • The whole spectral order is collapsed. (ie. Added together)
     • The spectral order is collapsed in the dispersion direction.

4. Partial Collapse allows the user to limit in the dispersion ("Y" axis) direction how much of the image will be included in the extraction. The default is to include the entire image. To use this feature :
   1. Click on the "Partial Collapse" button.
   2. On the image display left click on two points at the edges of the region you want included. Only the part of the image between these two points will be included.
   3. The display of the collapsed spectral order will change to just include the selected region.
   4. The wavelength range chosen is shown above the displayed cross dispersion.
5. Select Wavelength allows the user to choose in the dispersion ("Y axis") direction just one wavelength to be included in the extraction. The default is to include the entire image. To use this feature :
   1. Click on the "Select Wavelength" button.
   2. On the image display click on the one point you want to extract.
   3. The display of the collapsed spectral order will change to just include this wavelength element.
   4. The wavelength chosen is shown above the displayed cross dispersion.
6. If either "Partial Collapse" or "Select Wavelength" is chosen then the surrounding display box changes to :

   

   "W-Shift" allows the chosen wavelength (or wavelength range) to be changed. Enter a value into the text field and press "Enter". (Default value is "1.0".) The selected wavelength (or wavelength range) can then be changed by the value in the "W-Shift" field by clicking on the "/\" (up) or "\/" (down) buttons. The new wavelength (or wavelength range) is shown above the displayed cross dispersion. The units of wavelength change are in image resolution elements. These approximately correspond to pixels in the detector array.
   

7. Additionally, if wanted, another curve can be plotted over the displayed cross dispersion plot.
   This can be done using one of the "Overplot Calibration" or "Overplot Select" buttons :
   1. "Overplot Calibration" - This will overplot the corresponding "bcdnod" calibration file. (See Calibration Files.)
      Note : "bcdnod" files only exist for "1st" and "2nd" nod position calibration. There are no "center" position "bcdnod" calibration files.
      Attempting to use "Overplot Calibration" for an image that has no corresponding "bcdnod" calibration file will display the warning message :

      

      Click "OK" to return to the Manual Source Finder.

      If "Overplot Calibration" is selected and one of "Partial Collapse" or "Select Wavelength" has been previously selected
      then the overplotted data will also be confined to the save wavelength range as the displayed data.
      if one of "Partial Collapse" or "Select Wavelength" has not been previously selected then the entire wavelength range of the overplotting data will be displayed.
      In this case a warning message will appear :

      

      Click "OK" to continue overplotting.

   2. "Overplot Select" - This will display a selection window which allows any FITS format file to be overplotted.
      In all cases the file selected for overplotting MUST have at least one of the FITS header keywords FOVID, FOVNAME and APERNAME with the same values as the displayed data.
      If they do not then a warning message will be displayed and overplotting will not take place. Click "OK" to return to the Manual Source Finder.
      If the module (SL, LL, SH or LH) cannot be ascertained from the FITS header keywords FOVID, FOVNAME and APERNAME then a warning message will be displayed
      "Overplotting module cannot be ascertained" and overplotting will not take place. Click "OK" to return to the Manual Source Finder.
      

   Once a file (calibration or otherwise) is selected for overplotting it will be overplotted in blue over the displayed cross dispersion plot :

   

   Once a file has been overplotted then the surrounding display box changes to :

   

   These controls allow the overplotted data to be moved and scaled relative to the original data :

   • "X-Shift" allows horizontal movement. The value in the text field determines the increment in cross dispersion pixels (default value = 1.0).
     Click "->" for rightwards movement, "<-" for leftwards movement.
   • "Y-Shift" allows vertical movement. The value in the text field determines the increment in average intensity units (default value = 1.0).
     Click "/\" for upwards movement, "\/" for downwards movement.
   • "X-Scale" multiples the x-axis data by the value in the text field (default value = 1.0). Enter a value in the text field and click "X-Apply".
   • "Y-Scale" multiples the y-axis data by the value in the text field (default value = 1.0). Enter a value in the text field and click "Y-Apply".

8. To select a source for extraction first select one of the buttons :
   • Gaussian (Default) - attempts to fit a gaussian curve in the cross-dispersion direction at each wavelength of the source spectral image.
   • Tapered Column - delineates a column around the source spectral image.
     This column is flared/tapered along the spectral image to accomodate width changes at different wavelengths.
   • Fixed Column - delineates a fixed width column around the source spectral image.
   • Optimal- performs an optimal extraction

   For a full description of each extraction type see Spectral Extraction Types.
   

9. Set left and right limits for the source(s) in the cross-dispersion direction.
   There are two ways to do this :

   1. Cursor Selection :
      • Click on the button "Define Source (cursor)".
      • Click on lower and upper bounds on the lower display box the delineate the source.
      • If "Gaussian" is set pick half-width full maximum points. A gaussian curve will be fitted the source. This source will subsequently be extracted with a Gaussian fit.
      • If "Tapered Column" or "Fixed Column" is set pick base points. A column will be delineated. This source will subsequently be extracted with a linear summation.

   2. Numeric Entry :
      Numeric Entry is only valid if "Tapered Column" or "Fixed Column" is selected.
      It will not work if "Gaussian" is selected. (Clicking "Define Source (numeric)" when "Gaussian" is selected displays an error message, click "OK" to continue.)
      
      • In the "X-Center" box enter the position (in pixels) of the column center.
      • In the "Width" box enter the width (in pixels) of the column.
      • Click on "Define Source (numeric)". A column will be delineated.
      </ul.

10. The selected region will be marked in red while the rest of the box will default to "Sky" and be marked in green.
    

    Eg. Left - "Gaussian" selected, right "Tapered Column" selected :



11. Click again on the button "Define Source" to define more sources. Multiple sources may be defined for one order.
    "Gaussian" "Tapered Column" and "Fixed Column" may be defined at the same time.
    If a second or subsequent source is defined the default sky region is removed and re-set after the secord (subsequent) source definition is complete.
12. The "Gaussian" option uses the IDL "gaussfit" routine. This does not always converge.
    When convergence is not achieved no source definition will be plotted.
    

    From the IDL help text :

    The GAUSSFIT function computes a non-linear least-squares fit to a function f(x) with from three to six unknown parameters.
    f(x) is a linear combination of a Gaussian and a quadratic; the number of terms is controlled by the keyword parameter NTERMS.

    (This description copyright Research Systems Inc.)

13. To remove the most recent source definition click on "!UnDo Last Source". To remove all source definitions click on "!UnDo All Source(s)".
14. The "Sky" defaults to the region(s) not selected as source(s). It is marked in green on the display box and always treated as "Tapered Column" extraction.
    It is used during Sky Subtraction During Extraction. If wanted "Sky" may be defined manually :
    
    • Click on "Define Sky (cursor)".
    • Click on lower and upper bounds on the lower display box the delineate the "Sky". This will be marked in green.
    • To define further regions of "Sky" click on "Define Sky (cursor)" again and then two more bounds on the display box.
    • To remove a given sky definition click on "!UnDo Last Sky". To remove all "Sky" definitions click on "!UnDo All Sky".

    |Note : |"Define Sky (cursor)" can only be used after at least one source region has been selected.
    Attempting to define one or more sky regions before a source has been defined will display the warning message :

    

    Click "OK" to continue. |

15. Once the relevant source(s) has/have been defined (with corresponding sky region(s) if necessary) it/they can be applied to extracting the data :
    • Click one of :
      • This Order - Applies the selected source(s) and sky to the selected order.
      • All Orders - DEFAULT VALUE - Applies the selected source(s) and sky to all orders.
    • Click one of :
      • This BCD - Applies the selected source(s) and sky to the current BCD.
      • All BCDs - DEFAULT VALUE - Applies the selected source(s) and sky to all BCDs selected for this extraction.
        IE. All BCDs listed in the "Select BCD" drop down.
16. Click on "Apply Selection" to apply the source and sky definition(s) to the data.
    The application is controlled by the settings of the "This/All Orders" and "This/All BCD" buttons.

    |Note : |If "Apply Selection" is not clicked after "Orders" and "BCDs" are selected then the Manual Source Finder settings are ignored during extaction.
    IE. Attempting to extract data without clicking on "Apply Selection" will default to extraction to "Full". |

17. Click on "Save Plot" to save an image of the data with any overplot and defined source and sky region(s).
    This will display a pop-up window entitled "SMART Manual Source Finder Plot" :

    

    This will save a Postscript (".ps") file of the source display.
    The default file name is "smart_manual_extract.ps" and the default directory is the current woring directory.
    These can be changed by typing a different directory and/or file name into the text box labeled : "Output file name"
    The text box labeled "Additional Text" allows the user to add one line of text to the output ".ps" file, to be printed below the x-axis label.
    

18. Click on "Show List" to show a list of "Defined Sources" :

    

    NOTE : The "Apply Selection" button must have been clicked after source definition for entries to appear in this list.
    The list is cumulative - all defined sources are listed, even those that have been removed with the "Undo ..." buttons.
    Click on "Close" to return to the Manual Source Finder.
    This will also write to disk (in the current working directory) an ASCII ".txt" file of the displayed list.
    The file name is "smart_manual_extract.txt".

19. If necessary the same process can be applied indivdually to each order in the selected BCD (file) and/or each BCD selected for extraction.
    Change between BCDs by using the "Select BCD" drop down menu, change between orders by using the list of orders.
    Each time "Apply Selection" is clicked it appends the new source/sky locations to the current list.
    

    |Note : |If the "All Orders" and/or "All BCDs" selections are applied twice (or more) the last applied setting will over-ride the earlier one(s). |

20. To actually run the extraction click on the "Extraction" button at the bottom of the "SMART Manual Source Finder" window.
    Clicking "Cancel" will exit without performing any extraction and return to the "Dataset Manager" window.
21. The "Display Keywords" facility can be used after a source has been defined and applied to a (set of) BCD(s).
    Clicking the "Display Keywords" button displays a pop-up window :

    

    This pop-up window displays the source position definition keywords which are set by the Manual Source Finder.
    (See FITS Header Keywords for an explanation of the source position definition keywords.)
    Click "OK" to continue.

    NOTE :
    Only the keywords for the first order of the first BCD are displayed.
    If a source has been defined in another order and then applied to "all orders" then the values of the keywords will be the same for all orders.
    If a source has been defined in another BCD and then applied to "all BCDs" then the values of the keywords will be the same for all BCDs.

    NOTE :
    If the "Display Keywords" button is clicked then no actual extraction takes place.
    Once "OK" is clicked the user is returned to the SMART Dataset Manager.

Two additional tools exist at the bottom left-hand corner of the window :

• Save X-Section: Saves a ".xdr" file of the cross-sections of the slit at each wavelength element.
  The structure of the file is as follows for each wavelength :
  • 'DISPERSION', array of 100 numbers
  • 'INTENSITY', array of 100 numbers
  • 'LAMBDA', the wavelength
  • 'LAM_MIN', the minimum wavelength, theoretically should be the same as LAMBDA
  • 'LAM_MAX', the maximum wavelength, theoretically should be the same as LAMBDA
  • 'MODULE', the module
  • 'ORDER', the order
  • 'FOVID', the field-of-view ID
  • 'FOVNAME', the field-of-view name
  • 'APERNAME', name of the aperture
  • 'LINENUM', the line number

  Currently the number of wavelength elements is hard-coded in sm_mandefine_1.pro, and this number differs from the actual number of wavelengths
  as given by the newest versions of the IRS wavesamp (S11 and S12).

• Plot X-Section: Plots the cross-section of the of the slit as shown below :

The plot may be rotated about either the "X" or "Z" axis.
To rotate enter the required angle of rotation in the box(es) :

1. Rotation angle about the X axis :
2. Rotation angle about the Z axis :

Then click on "Plot" to display the rotated plot.
Click on "Reset Angles to Default" to return the plot to its original, default angle presentation.
(X axis default display angle = 40.0 degrees, Z axis default display angle = 30.0 degrees.)

Click on "Quit" to close the "X-Section Data Display" window and return to the "SMART Manual Source Finder" window.

Note :

As with other extractions in SMART manually set extraction is effected by the setting of the "sm_fwhmfactor" callibration parameter.
See the SMART Calibration Selection page for details. |