2. The Spitzer archive interface software, and data from AOR 7130112 (all wavelengths, post-BCD data). See Recipe 1 for instructions on downloading the data for the AOR. For this specific example we will use just the short-low data. Specifically, within the r7130112/ch0/pbcd/ directory, using the tool "imhead" (part of the WCS tools package: http://tdc-www.harvard.edu/software/wcstools/index.html), you can check the keyword "FOVNAME" in the *bksub.fits:
unix% ls *bksub.fits
SPITZER_S0_7130112_0002_6_A14567688_bksub.fits
SPITZER_S0_7130112_0002_6_A14567695_bksub.fits
SPITZER_S0_7130112_0002_6_A14567703_bksub.fits
SPITZER_S0_7130112_0002_6_A14567711_bksub.fits
unix% imhead *bksub.fits | grep 'FOVNAME'
FOVNAME = 'IRS_Short-Lo_2nd_Order_1st_Position' / Field of View Name
FOVNAME = 'IRS_Short-Lo_2nd_Order_2nd_Position' / Field of View Name
FOVNAME = 'IRS_Short-Lo_1st_Order_1st_Position' / Field of View Name
FOVNAME = 'IRS_Short-Lo_1st_Order_2nd_Position' / Field of View Name
We will extract a spectrum from the first image in the list, which is shown below. The dark pixels have large values, and the white pixels have small values (or NaN between the orders).
Note that you see two spectral traces. The one on the left is positive, and the one on the right is negative. The left trace (1st nod position) has been background-subtracted using the the 2nd nod position. This leaves a negative trace in the 2nd nod position. You will be extracting the left, positive, nod 1 trace.
12.2 Why use the command-line version of SPICE?
If you have only a handful of spectra to extract, we suggest that you use the GUI version of SPICE. The GUI version provides visualization features (2D spectrum display, profile plots, ridge overlays, etc.) which can help you ensure that your extraction is going as desired. You can find examples of how to run the SPICE GUI later in this Cookbook.
If you have a large number of spectra that must all be reduced in an identical way, one option is to use the SPICE GUI in batch mode. You can find an example of how to do this embedded in the DARK_SETTLE recipe in this Cookbook (Recipe 10).
If you have a huge number of spectra and/or limited computer memory, batch mode may be insufficient to reduce all of your spectra in one batch. In that case, you may either choose to run multiple batches, or to use the command-line version of SPICE to write a script to reduce your spectra.
If you choose to write a script, we recommend that you first use the GUI on a few of your spectra to experiment with your extraction parameters. You can then use the command line to script the remainder of your extractions using the same, optimized parameters. Every time the GUI runs, it writes out the corresponding command-line parameters. Check the spice*log files in your .spot/ directory. For each module, the input parameters are listed on separate lines for improved readability. To execute these on the command line, you will have to reformat them into one line. In addition, you must make sure that the SPICE binaries are in your path. (On a Mac, these binaries can be found in the bin/ subdirectory of your installation. For Solaris they can be found in the platform/sun/bin subdirectory.)
Below we go through an example of how you would execute these commands to perform a regular, standard-width, point-source extraction on a SL1 IRS spectrum. You will need to modify these parameters if you are using a different module or if you wish to perform a custom-width extraction. We strongly recommend that you make your modifications using the GUI first, and then copy those parameters when constructing your command-line syntax.
12.3 Run the PROFILE Module
The first step in the extraction process is to compute and plot the mean spatial flux profile across all user-selected orders. This will help us to identify the extraction window in the next step.
To run PROFILE from the command-line, first make sure that the PROFILE binary, found in the bin/ subdirectory of your installation, is in your path. Then issue the following (long) one-line command in a directory which contains your bksub.fits file and its associated mask (bkmsk.fits) file. Please note that you will have to modify the command below to provide the full path to the cal/ directory in your SPICE installation.
You are free to modify the values for the above input flags. You can type 'profile' with no argument at the prompt for a brief description of each possible input parameter. Also, you may wish to inspect the contents of the file spice/cdf/*/*_settings.prop to help you decide which values to give the input flags for data with a particular CAL_SET. The flags used above are described below.
i - The name of the input 2D spectrum from which you wish to extract a 1D spectrum.
b - The mask file associated with the input spectrum.
fb - Fatal bit pattern for the mask file. Set this to the decimal representation of the fatal bit flags. Pixels with the specified flags will be excluded from SPICE extraction. See Appendix B of the SPICE Manual for instructions on how to calculate the fatal bit pattern. Default value is 18432.
- The name of the output table which will hold the wavelength-collapsed average spatial profile for the selected orders. Default value is (input file).profile.tbl.
q - The name of the output qa file. Default value is (input file).profile.qa . This file tells you six things about the profile:
profMaxFlux - max value of dn for all cuts
profLocMaxFlux - location (%) of max dn cut
profMaxStdev - max value of stdev for all cuts
profLocMaxStdev - location (%) of max stdev cut
profMaxRStdev - max value of stdev/dn for all cuts
profLocMaxRStdev - location of max stdev/dn cut
t - The name of the *psf_fov.tbl calibration table which codes the order to be extracted for each FOVID, the default ridge location, and the extraction aperture width at a fiducial wavelength.
w - The name of the *wavesamp.tbl file. This file specifies the location of the spectral orders on the array in x-y coordinates. It consists of pseudorectangles which describe the fractional pixels which comprise each wavelength in the spectrum. You should choose the appropriate file in the cal/ subdirectory of your SPICE installation. The file you choose should match both the Spitzer pipeline version with which your data were processed and the IRS module with which you are working.
c - The PROFILE module divides each pseudorectangle into this number of cuts and integrates the signal within each cut. Allowed values are integers between 1 and 2000. We recommend that users keep this at the default value (1000 for SL and LL; 200 for SH and LH) adopted by the SPICE GUI.
Here again we see two features, a positive one on the left and a negative one on the right. Recall that the left peak represents the background-subtracted nod 1 spectrum, while the right-hand dip represents the sky background in the nod 1 image minus the nod 2 spectrum.
12.4 Run the RIDGE Module
The next step in the extraction process is to use the RIDGE module to identify the location for point source extraction by identifying the peak in the PROFILE output, or by using a user-specified fractional location along the slit.
To run the RIDGE module from the command line, try the following. Please note that you will have to modify the command below to provide the full path to the cal/ directory in your SPICE installation.
You are free to modify the values for the above input flags. You can type 'ridge' with no argument at the prompt for a brief description of each possible input parameter. Also, you may wish to inspect the contents of the file spice/cdf/*/*_settings.prop to help you decide which values to give the input flags for data with a particular CAL_SET. The flags used above are described below.
p - The output table from running the PROFILE module in the previous step.
f - The *fov.tbl file, which codes the order to be extracted for each FOVID, the default ridge location, and the extraction aperture width at a fiducial wavelength.
m - The number of points to use for median filtering (LO-RES only). Must be ODD.
s - The number of sigma to require the peak to be above the mean (LO-RES only). Must be between 0.0 and 10 (inclusive). The default is 5.
g - The width, given in plus-or-minus percent of the array in the cross-dispersion direction, to be analyzed, centered on expected position (LO-RES only). Allowed values are floats from 0.0 to 100, default is 100.0. e.g. if you wish to include 25% of the array either side of the profile center, giving you a total extraction width of 50% of the array, you would set a value of 25.0.
- The output table containing the x,y position of the peak for each order and each wavelength.
i - The name of the *wavesamp.tbl file. This file specifies the location of the spectral orders on the array in x-y coordinates. It consists of pseudorectangles which describe the fractional pixels which comprise each wavelength in the spectrum. You should choose the appropriate file in the cal/ subdirectory of your SPICE installation. The file you choose should match both the Spitzer pipeline version with which your data were processed and the IRS module with which you are working.
Here we demonstrate two options for performing the extraction: regular and optimal (flux-weighted).
To perform a regular extraction within a user-specified window, try the following. Please note that you will have to modify the command below to provide the full path to the cal/ directory in your SPICE installation.
You are free to modify the values for the above input flags. You can type 'extract' with no argument at the prompt for a brief description of each possible input parameter. Also, you may wish to inspect the contents of the file spice/cdf/*/*_settings.prop to help you decide which values to give the input flags for data with a particular CAL_SET. The flags used above are described below.
i - The name of the input 2D spectrum from which you wish to extract a 1D spectrum.
- The name of the output table, which will contain the 1D spectrum in units of electrons per second.
b - The name of the mask file that goes with the input 2D spectrum.
fix - This controls if the NaNs should be replaced with approximated values before doing extraction. A value of 0 means "don't replace". An integer, N, means that for each NaN pixel, the N rows above and N rows below are averaged column by column within the order, and then a line is fit to these column averages to approximate the NaN. Default is 2.
nanDrop - Wavelength bins with NaNs will be removed from the output spectrum if this is set to 1. Default is 0, with te NaN fluxes set to -9999.
f - Fatal bit pattern for BMasks. See Appendix B in the SPICE Manual for the allowed values and a description of how to calculate the fatal bit pattern. Default = 16384.
e - The name of the uncertainty file that goes with the input 2D spectrum.
r - The name of the output table from running the RIDGE module in the previous step.
ord - This refers to the spectral order, and is used for low-resolution extractions only. You can set this to:
p - The name of the *psf_fov.tbl calibration table which codes the order to be extracted for each FOVID, the default ridge location, and the extraction aperture width at a fiducial wavelength.
height1 - Sets the wavesamp height. Set to 1 to force wavsamp height to 1 pixel; set to 0 to use actual height. Default = 0.
w - Width (in pixels) of the extraction aperture at the reference wavelength. Default for HI-RES is to use the full width of the order, and for LO_RES to use the value given in the psf_fov.tbl table specified by the "-p" flag.
l - Reference wavelength (in microns) of the aperture width specified by the "-w" flag. A value of 0 selects a constant width extraction aperture. Default is to use the value given in the psf_fov.tbl file specified by the "-p" flag.
full - Extraction type; 0=sub_slit and 1=full_slit. Default is sub-slit unless all of the following are true: (a) the "-w" flag is not explicitly set; (b) this is not a HI-RES observation; (c) this is not a LO-RES center position observation.
norm - Normalize the fluxes. Default is no normalization.
0 = no normalization 1 = divide by height of wavesamp rectangle 2 = divide by area of wavsamp rectangle
Set to 1 for S18.7 SL, LL, LH. Set to 0 for S18.7 SH. Set to 1 for S17.2 LH. Set to 0 for S17.2 SL, LL, SH. Set to 0 for all other CAL_SET versions.
To perform optimum extraction, try the following. Please note that you will have to modify the command below to provide the full path to the cal/ directory in your SPICE installation.
b - The name of the mask FITS file that goes with the input 2D spectrum.
pixel_scale - Pixel size (arcsec/pix) in input image.
fatal - Fatal bit pattern for BMasks. See Appendix B in the SPICE Manual for the allowed values and a description of how to calculate the fatal bit pattern. Default = 16384.
nanDrop - Wavelength bins with NaNs will be removed from the output spectrum if this is set to 1. Default is 0, with te NaN fluxes set to -9999.
keepnans - Set this to 1 if you wish a rectified pixel to be set to NaN if any of the corresponding pixels in the original image are NaNs. Default is to approximate with remaining non-NaN pixels.
area_width - Width in pixels of rectified area (odd integer).
resamp - Interpolation type to go from BCD image to rectified image. 0=nearest 1=weighted bilinear 2=unweighted bilinear
w - The name of the *wavesamp.tbl file. This file specifies the location of the spectral orders on the array in x-y coordinates. It consists of pseudorectangles, which describe the fractional pixels that comprise each wavelength in the spectrum. You should choose the appropriate file in the cal/ subdirectory of your SPICE installation. The file you choose should match both the Spitzer pipeline version with which your data were processed and the IRS module with which you are working.
ridge - The name of the output table from running the RIDGE module.
p - Input stellar profile template FITS file.
r - The name of the output rectified flux FITS file.
r_unc - The name of the output rectified uncertainty FITS file. This is an optional intermediate product. SPICE will not write out this file unless an output filename is specified by the user.
r_bmask - The name of the output rectified BMask FITS file. This is an optional intermediate product. SPICE will not write out this file unless an output filename is specified by the user.
r_offset - The name of the output rectified offsets FITS file. This is an optional intermediate product. SPICE will not write out this file unless an output filename is specified by the user.
clip_width - Width (in pixels of the original non-rectified image) of the extraction aperture at the reference wavelength. Default is half the width of the order.
clip_lambda0 - Reference wavelength (in microns) of the aperture width specified with the "-clip_width" flag. Default is to use a constant width extraction aperture.
u - The name of the uncertainty file that goes with the input 2D spectrum. If you do not specify an uncertainty file, the extraction will be profile-weighted only, and will use the default uncertainty value set by the flag "default_unc" for all pixels.
height1 - Sets the wavesamp height. Set to 1 to force wavsamp height to 1 pixel; set to 0 to use actual height. Default = 0.
norm - Normalize the fluxes. Default is no normalization.
0 = no normalization 1 = divide by height of wavesamp rectangle 2 = divide by area of wavsamp rectangle
Set to 1 for S18.7 SL, LL, LH. Set to 0 for S18.7 SH. Set to 1 for S17.2 LH. Set to 0 for S17.2 SL, LL, SH. Set to 0 for all other CAL_SET versions.
The relevant output from the optimal extraction is SPITZER_S0_7130112_0002_6_A14567688_bksub.extract.tbl, the one-dimensional optimally extracted spectrum, in units of electrons per second. Note that the regularly-extracted spectrum and the optimally-extracted spectrum have the same name in this example (and that is the default used by the GUI as well).
12.6 Run the TUNE Module
The final step is to use the TUNE module to convert the extracted spectrum from units of electrons per second to flux density (Jy). The conversion is only valid for the standard extraction width.
To run the TUNE module from the command line, try the following. Please note that you will have to modify the command below to provide the full path to the cal/ directory in your SPICE installation.
You are free to modify the values for the above input flags. You can type 'irs_tune' with no argument at the prompt for a brief description of each possible input parameter. Also, you may wish to inspect the contents of the file spice/cdf/*/*_settings.prop to help you decide which values to give the input flags for data with a particular CAL_SET. The flags used above are described below.
i - The output table from running the EXTRACT module in the previous step.
t - Name of tuning table.
m - mode (tune_up OR tune_down). Virtually all users will wish to use the "tune_down" option. The "tune_down" value means to apply the fluxcon table in the normal way, dividing by the factors. The "tune_up" value means to multiply by the factors. If you run irs_tune with tune_down on untuned data, you get tuned data. If you run irs_tune with tune_up on tuned data, you get the untuned data back.
- The desired name of the output flux-calibrated spectrum, in units of Jy.
a - Tuning components from the *_fluxcon.tbl to apply. Default = 3. Below, "fluxcon" refers to the conversion factor from electrons per second to Jy, while "tune" refers to the remaining wavelength dependent calibration factors. Nearly every user will wish to set this value to 3 so that both the fluxcon and tune options are applied.
