Spitzer Documentation & Tools
Spitzer Data Analysis Cookbook

Recipe 18.            IRSCLEAN, COAD, and SPICE: Mrk 273 LH Data

In this recipe, we describe how to reduce high-resolution IRS spectra using IRSCLEAN to remove rogue pixels, COAD to combine images taken at the same nod position, and SPICE to perform the extraction. 

18.1            Requirements

To follow along with this recipe, you will need to use the following software:


- the Spitzer Heritage Archive, which is a web-based tool that does NOT require any installation on your computer.  You can find it at http://irsa.ipac.caltech.edu/applications/Spitzer/SHA/.


- IRSCLEAN, which is an IDL tool that you can download at http://irsa.ipac.caltech.edu/data/SPITZER/docs/dataanalysistools/tools/irsclean/.  To run IRSCLEAN, you must have IDL version 5.5 or later installed.


- SPICE, which is a Java-based tool that can be downloaded at http://irsa.ipac.caltech.edu/data/SPITZER/docs/dataanalysistools/tools/spice/.


18.2            Download and Examine the Example Data Set

The example data set that we will use for this recipe consists of high-resolution IRS Staring-Mode observations of the nearby ULIRG Mrk 273 at a redshift of z = 0.038.  Consult Recipe 1 and Recipe 2 to learn how to use the Spitzer Heritage Archive to download AOR 4980224.  For this recipe, you will need the BCD (Level 1) and PBCD (Level 2) data for the Long-High module (channel 3).


Once you download the data to the directory of your choice (which we will now refer to as yourdirectory/), you should examine the files in the directory




At the time of writing of this recipe, the data for this AOR were reduced with Spitzer pipeline version S18.7.0.  Check the header keyword 'CREATOR' in any of the files in the above directory to see which pipeline version your downloaded data set was reduced with.  Depending on the results, you might expect to see small differences from the results presented here and those you achieve with your data set.


By examing the header keyword "FOVNAME" in the *bcd.fits files in the above directory, you will notice that there are four nod 1 files (FOVNAME = 'IRS_Long-Hi_1st_Position') and four nod 2 files (FOVNAME = 'IRS_Long-Hi_2nd_Position').  In the image below, we show an example of each.


Example nod 1 (left) and nod 2 (right) BCD images of Long-High (channel 3) IRS spectroscopy of the ULIRG Mrk 273.  There are four BCDs taken in each nod position for this AOR.  You can see the light from Mrk 273 illuminating the different orders, with the spectral trace shifting leftwards from nod 1 to nod 2.  Also visible are many hot pixels.  An important part of our reduction is to ensure that those hot pixels do not impact our extracted spectra.

It is also useful to examine the files in the Post-BCD directory, which is:




The relevant files here are the two *coa2d.fits files, which are the co-added nod 1 files and the co-added nod 2 files, with some additional masking between the orders.  These files are illustrated below.


Nod 1 (left) and nod 2 (right) *coa2d.fits files for Long-High (channel 3) IRS observations of Mrk 273.  Each was constructed from four BCD images.  Hot pixels remain along the spectral trace.  This indicates that we may need to do some hot pixel cleaning before spectral extraction.

Before proceeding with the reduction, it is also worth examining the *tbl files in the pbcd/ directory.  These are ascii tables that contain the extracted spectra.  Using the headers within the files for guidance as to their contents, you can use your favorite graphing program to plot the spectra, as we have done below.


Long-High spectra of Mrk 273, as taken from the pbcd/ directory.  This represents the simplest reduction possible, as it was accomplished by an automated pipeline.  Adjacent orders are plotted in different colors for clarity.  No cleaning or trimming of the spectra has been performed.

The first thing we notice about the spectra above is that the edges of the orders tend to plummet.  This is easily solved by trimming the orders, since there is a small but significant overlap between orders.  Users are free to use their judgment when trimming, but we use the values below:

order:        11      33.8268      37.1360 -->  34.0  36.9

order:        12      31.1221      34.1383  --> 31.5  34.0

order:        13      28.7773      31.5925  --> 29.0  31.5

order:        14      26.7647      29.3831  --> 27.2  29.0

order:        15      25.0177      27.4652  --> 25.5  27.2

order:        16      23.4824      25.7797  --> 23.5  25.5

order:        17      22.1149      24.2784  --> 22.3  23.5

order:        18      20.8966      22.9408  --> 21.0  22.3

order:        19      19.7948      21.7494  --> 20.0 21.0

order:        20      18.8294      20.6542  --> 19.1  20.0


This simple trimming makes for a much smoother spectrum.  However, it's obvious that the order mismatch is large for the lowest orders (longest wavelengths).


Same as the previous image, but with some trimming of the orders.


Some real spectral lines have been indicated in the above plots.  Noise, hot pixels, and detector fringing (which may be improved using IRSFRINGE) remain.  In the next section, we will investigate and remove the contribution from hot pixels.

18.3            Remove the Rogue Pixels Using IRSCLEAN

Assuming that you have IRSCLEAN installed, you can simply type the following at the IDL prompt and have it guide you through the process of cleaning your BCD images.


IDL>irsclean_mask, datarange=[0,0]


The datarange parameter describes the minimum and maximum pixel values used in the display of the fits image.  By setting it to [0,0], we will be able to interactively adjust the display when we examine and (optionally) edit the mask.  The datarange parameter is one of many command-line options allowed by IRSCLEAN.  For a full listing, type the following at the IDL prompt:


IDL>irsclean_mask, /help


Using a minimum set of input parameters makes IRSCLEAN interactively walk you through the cleaning process.


Once you issue the first command above, you will see the following screen pop up:



You can change the filter to read *bcd.fits to get a list of just the *bcd.fits files.  Select one of these and click "OK".  You will then be asked to select a rogue pixel mask file:



IRSCLEAN will choose a default mask, which is what you want.  Click "OK".  (Alternatively, you may select "Cancel" to select no rogue mask.)  Note that the keyword /CampaignRmask automatically picks the campaign rogue mask, bypassing this dialog widget.  Next you will be presented with the IRSCLEAN Image Display Scaling screen:



As printed at the bottom of this screen, you can right-click on this screen and drag the cursor around until you achieve the kind of display you desire.  The vertical white stripes are the different orders of the spectrum.  The greyscale is set so that the white parts are illuminated.  The black pixels are NaNs, and will not be included in the extraction by SPICE.  You want to adjust the display until it becomes obvious which pixels are anomolous (other than the NaNs).  You only need to worry about the white illuminated strips.  The interorder regions won't be used in the extraction.  It can be difficult to find a datarange that fits all of the orders, but you can rescale the image during Mask Editing (see below) by typing the "r" key.  This allows you to go throught he process multiple times, doing a few orders at a time.


Once you have chosen a display setting that you like, go to "File"--"Quit" to proceed with the mask editing process.


You will be presented with the IRSCLEAN Mask Editing screen, which looks like this:













In the terminal in which you started IRSCLEAN, you'll see these instructions:





          (requires 3-button mouse)


       Blue = bmask-ed pixel (ignored in cleaning and rogue finding)

       Red = Rogue pixel


           LEFT  -  toggle rogue mask pixels on and off.

         MIDDLE  -  quit without saving.

          RIGHT  -  clean data using current mask




The bmask is the mask that is associated with the *bcd.fits image, and includes pixels that were flagged throughout the pipeline run.  You will notice that all of the NaNs (black pixels) are shown in blue, which means they are flagged in the bmask.  The campaign rogues from the mask that you uploaded into IRSCLEAN are shown in red.  These include anomolous-looking pixels (too bright or faint compared to neighboring pixels).  At this point you can follow the directions above to edit the mask.  For the purposes of this example, we will simply use the campaign rogues as is.  To do this, you can just right click on this window (or type "c").



When the screen above shows up, click on "Yes".


Next you will be prompted to enter the filename for the output mask:



IRSCLEAN will choose a default value that will work fine.  Click "OK". 


Now you will be asked if you wish to save the cleaned image:



Click "Yes".


Now you will be asked to enter the filename for the output clean image:



IRSCLEAN will choose a default name that will work fine.  Click "OK".  Now IRSCLEAN will offer to clean other images based on the same mask.  Since you didn't edit the campaign rogue mask, you can use it to clean your other *bcd.fits files.  Simply edit the Filter field to read *bcd.fits.  Then choose all of the bcd files by holding down the control key for each selection.  Finally, click "OK".



Now you will be presented with a summary of images that you just chose:



If what you see is correct, go to the "File" menu and choose "Done with Stage 2".


You will see a lot of output to the terminal window in which you started IRSCLEAN.  At the end, it will tell you that you could have performed the same task by typing the following command at the IDL prompt:


IDL> irsclean_mask, 'r4980224/ch3/bcd/SPITZER_S3_4980224_0012_0000_10_bcd.fits', inRmask_File=['IRSCLEAN1.9/all_campaigns_roguemasks/b3_rmask_IRS6.fits'], outRmask_File='r4980224/ch3/bcd/SPITZER_S3_4980224_0012_0000_10_rmask.fits', outClean_File='r4980224/ch3/bcd/SPITZER_S3_4980224_0012_0000_10_bcd_clean.fits', filesToClean=['r4980224/ch3/bcd/defaultlist.txt'], DataRange =[-181.434,979.094]


You have now just cleaned your *bcd.fits images based on the campaign rogue masks.  You will find the results in your bcd/ directory.  The most important of these are the *bcd_clean.fits, *bmask_clean.fits, and *func_clean.fits.


At this point it is a good idea to compare the original *bcd.fits images to their cleaned versions (*bcd_clean.fits), and to make sure you are happy with the results.


Original *bcd.fits image (left) and the corresponding *bcd_clean.fits image (right).  The images look mostly the same, but differ in detail.  The green circles show one example where the images look different.  One of the rogue pixels near the spectral trace has been removed.  Other changes exist in the images, and the user is encouraged to inspect the fits images closely to discover them.

18.4            Coadding your BCD files

The real test of whether the cleaning process has been worthwhile is to compare the final spectrum with the uncleaned spectrum that we previously examined from the pbcd directory.  Before we can do any extraction, we must first coad the *bcd_clean.fits files taken at each nod position.  You can do this using the IDL software COAD, which can be found at http://irsa.ipac.caltech.edu/data/SPITZER/docs/dataanalysistools/tools/coad/.


To use COAD, first create a list of the cleaned bcds that you wish to coad.


% ls *bcd_clean.fits > mixedbcdlist.txt


This list will contain both nod 1 and nod 2 positions, but COAD will figure it out and produce one coadded file for each position.  To run COAD on this mixed list, type the following at the IDL prompt:

IDL> doall_coads, 'mixedbcdlist.txt', /verbose, fatalbits=[8,12,13,14]


The result cleaned, coadded files and their associated uncertainty and mask files are:


SPITZER_S3_4980224_0012_10_coa2d.fits  SPITZER_S3_4980224_0013_10_coa2d.fits


SPITZER_S3_4980224_0012_10_c2unc.fits  SPITZER_S3_4980224_0013_10_c2unc.fits


SPITZER_S3_4980224_0012_10_c2msk.fits  SPITZER_S3_4980224_0013_10_c2msk.fits


At this point it is useful to blink back and forth (using ds9) between the the coadded images you have just created and the corresponding images in the pbcd/ directory (e.g. SPITZER_S3_4980224_0012_10_coa2d.fits versus SPITZER_S3_4980224_0012_10_E5480030_coa2d.fits).  The most noticeable difference will be that the pbcd pipeline masks the interorder regions, and COAD does not.  If you take a more detailed look, you should see some anomolous pixels in the pbcd/ image that you have removed in your image.

18.5            Extract the Spectrum Using SPICE

Now we can use SPICE to extract spectra from our coadded images.


Start up SPICE and then go to "File"-->"Open SPICE Generic Template"-->"Point Source with Regular Extract".  You will see the following screen:



You must fill in all of the values requested near the top, under "Initialize Parameters and Files".  For "Image File", choose SPITZER_S3_4980224_0012_10_coa2d.fits.  SPICE should automatically find the corresponding mask and uncertainty files.  Then choose the output directory of your choice. 


Next click on the green arrow at the top of the SPICE window.  When the flow has completed, you will be able to see your extracted spectrum at the bottom of the SPICE window.  You will find the ascii version of this spectrum in the output directory that you chose, with a suffix of *spect.tbl.

To extract the other nod, rewind the flow to the beginning, put in the nod 2 *coa2d.fits file, and run the flow again.  Alternatively, you can open a 2nd flow for the other nod.  That way you can click back and forth between the 2 nod spectra.


Now you have your own cleaned versions of the nod 1 and nod 2 spectral extractions:





You can  plot these up in the same way you did before:




You will notice that the spectra look very, very similar.  However, if you perform a detailed comparison, you will find small differences.  The largest differences occur at the longest wavelengths.  In this case, there are two lines in the longest-wavelength order, so it is worth cleaning the spectrum prior to extraction.  You may wish to go back and pay particular attention to this order and edit your mask accordingly.


So that you can check your results agains ours, we provide our cleaned, extracted spectrum below: