PEGA-CCDPhot-HOWTO John P. McFarland v1.0, 2002-07-10 The following are the procedures necessary to perform aperture photometry on CCD frames using the CCDPHOT reduction package for IDL written by Marc Buie of Lowell Observatory . The author's description of CCDPHOT is located at http://www.lowell.edu/users/buie/idl/ccdphot.html. ---------------------------------------------------------------------------- Table of Contents 1. Introduction 2. Pre-processing 2.1 FITS Header Keywords 2.1.1 CCDFAME (or equiv.) 2.1.2 AIRMASS (optional) 2.1.3 EXPTIME 2.1.4 FILTERS (or FILTNAME or equiv.) 2.1.5 OBJECT 2.1.6 DATE-OBS (or equiv.) 2.1.7 UT 2.2 Plate Scale 3. Image Dialogs 3.1 CCDPHOT 3.1.1 Exit 3.1.2 Raw/Processed 3.1.3 Prev/Next 3.1.4 Auto 3.1.5 ViewHeader/Write Fits 3.1.6 Calibration Environment 3.1.7 Image Frame: Select File 3.2 Itool Image Parameters 3.2.1 Dismiss/Verify 3.2.2 Image File Name 3.2.3 Airmass 3.2.4 Exposure Time (seconds) 3.2.5 Filter Code 3.2.6 Object 3.2.7 Date of Observation 3.2.8 Start Time (UT) 3.2.9 Julian Date (mid-time) 4. Itool Photometry Parameters 4.1 Dismiss/Load/Save 4.2 Photometry log file name 4.3 Aperture radius (pixels) 4.4 Inner/Outer radius of sky annulus (pixels) 4.5 Local maximum box radius (pixels) 4.6 Gain of CCD (e-/DN) 4.7 Plate scale (arcseconds/pixel) 4.8 Search for local maximum/Use exact position 4.9 Nominal extinction (mags/airmass)/Zero point 5. Itool Photometry Template Manager 5.1 Dismiss/Load/Save 5.2 Add/Delete Template 5.3 Purge 5.4 Filename: Select 5.5 Template Name List 5.6 Change name of selected template: 5.7 Template Add/Activate Dialog 5.7.1 Add/Activate 5.7.2 Delete Object 5.7.3 Purge Objects 5.7.4 Object List 5.7.5 Change name of selected object: 6. Photometry 6.1 Starting CCDPHOT 6.2 Verifying Parameters 6.3 Constructing a Template 6.4 Photometry Walk-Through 7. Conclusion 1. Introduction CCDPHOT is a very powerful tool which can perform aperture photometry on multiple objects in a single frame. It is capable of following slight shifts (typically not more than 10 pixels) in image position between frames, allowing rapid reduction of large sequences of frames. It does this by using an auto-centering algorithm on all the objects and notes the difference in positions from a known template. This template is unique for each object/CCD setup. Running IDL for CCDPHOT: In order for CCDPHOT work properly, IDL must be run from a C-shell after the setup file idl_setup is sourced: ...]$ csh ..~]$ source /usr/rsi/idl/bin/idl_setup (or /usr/local/etc/idl_setup) ..~]$ idl . . . IDL> ccdphot If it is run from BASH, the Itool widget will freeze and the only way to get out of it is to kill the IDL session manually. Also, despite the fact that you can change directories in IDL, it is often simpler to be in the desired directory before running IDL. 2. Pre-processing 2.1 FITS Header Keywords Before bringing images into CCDPHOT, the correct header keywords must exist in the FITS header and the keyword values should be accurate. It is not necessary to have specific names for the keywords since the names can be configured into CCDPHOT through the use of a keylist. The various FITS keywords necessary are listed below: CCDFNAME* AIRMASS EXPTIME FILTERS* OBJECT DATE-OBS* UT * denotes only the keywords that will likely need any attention 2.1.1 CCDFAME (or equiv.) The CCDFNAME FITS keyword should be of the form ccyymmdd.nnn. For example, the value of CCDFNAME for the very first frame taken on January 1, 2002 should be: 20020101.001 in the FITS header. There are other keywords which carry filenames, but CCDFNAME is the standard for the PEGA group. Note that there is no .fits extension on the end. This is important since later processing software has a limitation on the filename length. Also, this uniformity will allow more advanced software to handle the resultant output files properly. The "ccdfname" script will create the name of this form automatically. 2.1.2 AIRMASS (optional) This is an optional FITS keyword which allows CCDPHOT to calculate the extinction (mags/airmass) if included. 2.1.3 EXPTIME The length of the exposure in seconds. This is used to calculate counts per second, and, with the UT keyword (below), the mid- time of the exposure. 2.1.4 FILTERS (or FILTNAME or equiv.) This FITS keyword (or series of them) will usually denote a filter letter or filter code (usually numeric). It is desirable to use the one that has the letter designation (R for red, etc.) and for that letter to be capitalized. If not included in the FITS header, this keyword should be added. 2.1.5 OBJECT Obviously, the name of the object. This can take any form, but it is preferable to use all lower case letters and no spaces for uniformity. During creation of the photometry templates, this convention will be used since it is REQUIRED by the post- processing scripts. 2.1.6 DATE-OBS (or equiv.) The date keyword can be named many things: DATE, DATE-OBS, DATE-NEW, etc. We follow no specific convention. As long as the appropriate entry is made in the keylist, no problems should arise. If you notice a date reported incorrectly, or a bad Julian Date, it is most likely caused by an error associated with this FITS keyword. It should have the form ccyy-mm-dd or something similar. 2.1.7 UT The UT time of the observation. CCDPHOT adds half of the FITS keyword EXPTIME to the time read from the FITS keyword UT to get the mid-time of the exposure. This is then used to calculate the fractional day of the Julian Date. 2.2 Plate Scale The plate scale changes from setup to setup. In order to keep a consistent aperture for photometry, the plate scale must be known. The IDL routine ASTROMIT will calculate the plate scale provided the coordinates of at least 3 objects in a frame are known. It is ideal to have the objects separated by at least 1/4 of the chip in both the X- and Y-directions. The coordinates must be in degrees for both RA and DEC. The coordinates in degrees can be obtained from the USNO-A2.0 plates. These values for the objects and check stars can be found on PEGA finding charts at www.chara.gsu.edu/PEGA/finding.html. If the plate scale is already accurately known, ASTROMIT need not be used to calculate it. The procedure for calculating the plate scale with ASTROMIT is detailed in the PEGA data processing manual by Elizabeth Ferrara. It may be added here at a later time. One note, to be able to run ASTROMIT from the libraries (i.e. without having to copy the IDL program files to the current directory), IDL must be started from BASH in this way: ...]$ source /usr/local/PEGA/bin/idl_setup.ksh ...]$ idl . . . IDL> astromit, X, Y, RA, DEC 3. Image Dialogs Before describing any of the dialog boxes, it is important to note that CCDPHOT requires a carriage return (i.e. press the key) in any text field in order for the value in that text field to be registered. In some cases, CCDPHOT will store the value, in others, it will perform some action (e.g. open an image). 3.1 CCDPHOT Once IDL and CCDPHOT are started properly (see section 1.), the main CCDPHOT window is opened. This window allows you to choose the files to do photometry on. What follows is a quick explanation of the options in this window, clockwise from top left. 3.1.1 Exit Obvious. This will quit the entire CCDPHOT task, so be careful. 3.1.2 Raw/Processed Leave this at processed since the PEGA group process all of its data in IRAF before using CCDPHOT. 3.1.3 Prev/Next These buttons allow navigation through the images in a directory. The image names must be of the standard form ccyymmdd.nnn, where nnn must be sequential. The num-add script (described in the PEGA-Data-Processing-Tips-HOWTO, available by typing "pega-info" at a prompt), will rename the extensions sequentially to aid in this part of the photometry. 3.1.4 Auto Once CCDPHOT has successfully completed photometry on a template of objects, the "Auto" button can be used to continue through the series of images, doing the template photometry as it goes. There will be various things that will cause this to stop or otherwise give error messages. These instances will be discussed later. 3.1.5 ViewHeader/Write Fits These two are of little use to the PEGA group. Their meanings should be self-explanatory. 3.1.6 Calibration Environment Since the PEGA group calibrates it's raw data in IRAF, this section is unnecessary. 3.1.7 Image Frame: Select File Click on the "Select File" button to open a file chooser dialog box. This will allow you to pick the image to be loaded into the Itool image display. The filename or pathname of the image can also be entered into the text field to the right. In this case, hitting with focus on that text field will load the image directly. 3.2 Itool Image Parameters Once an image is opened, it will be displayed in the Itool window. This window has access to many options, but we are only concerned with three of them: Image Parameters, Photometry Parameters, and Template manager. The profiles dialog is also useful, but only in an informational sense. The Image Parameters dialog box is mostly for informational purpose, but can be used to modify image information on a frame-by-frame basis. The following is a description of the Image Parameters dialog box from top to bottom: 3.2.1 Dismiss/Verify The "Dismiss" button hides the Itool Image Parameters dialog box keeping the values in memory. The "Verify" button prints out a list of the current parameters that are in memory. This is to make sure that the dialog box values displayed are actually in memory. 3.2.2 Image File Name The name of the current file to which the following parameters apply. 3.2.3 Airmass Value from the AIRMASS FITS header keyword. 3.2.4 Exposure Time/Delta (seconds) The length of the exposure for the current image. The "Exposure Delta (seconds)" is for use with a type of FITS not used in the PEGA group. Just ignore it. 3.2.5 Filter Code Preferably the capitalized letter code for the filter used on the current frame. 3.2.6 Object The object name of the current image. 3.2.7 Date of Observation The UT date of the current image. 3.2.8 Start Time (UT) The UT start time of the current image. 3.2.9 Julian Date (mid-time) The Julian Date calculated at halfway through the exposure. 4. Itool Photometry Parameters 4.1 Dismiss/Load/Save The Dismiss button hides the Itool Photometry Parameters dialog box. The values are stored in memory despite this. Load and Save will load or save the photometry parameters from or to the file designated in the "Photometry parameters file name" text field. Remember to hit after entering the pathname/filename. 4.2 Photometry log file name Typically called phot.log, this file stores the output of the photometry. There should be n+1 lines per frame (n check stars available on the frame plus the object) stored in this file. This file is never overwritten by CCDPHOT. It is only appended to. The typical procedure is to move the phot.log file to the standard name format: ...]$ mv phot.log ccyymmdd.object_name.filter_code.aperture_as.log This is usually done after each day is reduced. 4.3 Aperture radius (pixels) Notice that this is a _radius_ not a diameter. After calculating the correct aperture (usually expressed as a diameter), it must be divided by 2. If this isn't done, too large an aperture will be used for the photometry, skewing the results. Typical the PEGA group uses apertures of 7" and 12" (" = arc seconds). The program takes the aperture in pixels (as noted above), so it must first be converted to pixels from arc seconds. To do this, simply divide the aperture in arc seconds by the plate scale in arc seconds per pixel. See section 4.7. 4.4 Inner/Outer radius of sky annulus (pixels) These values will differ depending on the aperture radius. It should always be at least a few pixels outside of the aperture, typically rounded up to the nearest factor of 5 (as long as its a few pixels higher). The default for the inner radius is 10 pixels, for the outer radius is 50. A good rule-of-thumb is to increase the outer radius by the same amount as the inner one. This gives a relatively constant area to the annulus. The actual value of the annulus area determines the offset of the instrumental magnitude to the actual magnitude. This must be taken into account using stars of known magnitude. The Zero point text field can be used to automatically adjust for this, but it must be known for a given aperture/annulus combination. Unfortunately, the zero point correction here is only for informational purposes. See section 4.9. 4.5 Local maximum box radius (pixels) This specifies how far away from the selected point the actual object is. It compensates for a selection which misses the exact peak of the object. Unfortunately, nearby stars or comic-ray spikes can fool this, but that is only a problem when the object is relatively faint. Reducing the radius or choosing "Use exact position" can reduce or eliminate this problem. See warning section 4.8. 4.6 Gain of CCD (e-/DN) If known, the gain adds accuracy to the instrumental error. Since the instrumental error is rarely, if ever, used by the PEGA group, this value should stay at the default of 1. 4.7 Plate scale (arcseconds/pixel) The full width at half maximum (FWHM) output to the .log file will be in pixels if this is set to 1, and in arc seconds if set to the actual plate scale. Since the FWHM in arc seconds will be calculated after the fact (if needed), leave this set to 1. 4.8 Search for local maximum/Use exact position Under most circumstances, this should be left to the default of "Search for local maximum". In the rare case where a brighter object is near the anchor point (the reference point for the photometry template), reducing the "Local box maximum radius" may not work. If such a problem arises, set this to "Use exact position" and be very careful with the anchor point selection. 4.9 Nominal extinction (mags/airmass)/Zero point These two are more for informational purposes than anything else. The extinction compensation adjusts the magnitude dependent on airmass, and the zero point correction provides the offset to the instrumental magnitude to bring it close to the actual apparent magnitude. Since the results of these corrections are only as accurate as the values, and since these values can change with filter, night, etc., the results are never written to the actual .log file. It is up to the user to apply these corrections manually at a later time. For the PEGA group, these should be left at their default of 0. 5. Itool Photometry Template Manager In order to perform photometry on multiple objects simultaneously, a template of the objects must first be created. This is where the template manager comes in. It allows the selection of the positions of an arbitrary number of objects. These objects positions are then updated using a centering routine. If the structure of the template changes too much between frames, a warning is issued and no auto-photometry can proceed until the discrepancy is corrected. This ensures that photometry is being done on only the objects specified. Following is a description of the Itool Photometry Template Manager dialogs: 5.1 Dismiss/Load/Save Unlike the other dialogs, this one should not be dismissed. If this is done, the newly created template is no longer active. See section 5.7.1. The Load/Save buttons work as expected after a filename is entered into the "Filename: Select" text field and a carriage return is entered with focus on that field. See section 5.4. 5.2 Add/Delete Template Once the Add Template button is pressed, another small dialog box with a text field pops up. Upon entering a template name followed by a carriage return, the new template can be selected in the Template Name List. See section 5.5. 5.3 Purge This button does exactly what it claims: purges a selected template from the Template Name List. See section 5.5. 5.4 Filename: Select This button/text field allows the selection of a file containing a pre-constructed template. As usual, a filename must be entered followed by a carriage return. 5.5 Template Name List This field lists the names of templates that the template manager knows about. Upon selection of one of these templates, the "Template Add/Activate Dialog" appears, allowing the template to be defined or activated. See section 5.7. 5.6 Change name of selected template: Just what it says . . . 5.7 Template Add/Activate Dialog Once a template is selected, this dialog pops up. It will allow detailed control of the templted selected. This dialog should remain open and in the "Active" state while photometry is being performed. 5.7.1 Add/Activate Initially, the "Add" option will be selected. This allows the template to be populated with a set of new objects. New objects are selected by simply left-clicking on the objects of interest. Once all the objects are selected, the template can be set active by selecting the "Activate" option. 5.7.2 Delete Object Delete a selected object from the object list. 5.7.3 Purge Objects Purge all objects from the Object List. A confirming dialog will come up to verify that this is the desired action. 5.7.4 Object List Contains the list of objects that photometry will be performed on in the order initially selected. For the PEGA group, this should be in numerical then alphabetical order. E.g.: object check1 check2 checkA checkB etc. 5.7.5 Change name of selected object: With a particular object selected, this text field will allow modification of the object name that will appear in the .log file. As usual, it must be followed by a carriage return to take effect. For the PEGA group, the names should be of a very specific form. The object name should be all lower case with no spaces in it. The comparison sequence of stars should be lower case "check" followed by the canonical comparison star designator as denoted on the finding chart for the object at the PEGA website. There should be no spaces in the comparison star names either (see section 5.7.4 for examples). The reason for such stringent requirements on the object names is that the "pegasort" script which so handily sorts the .log file into a more manageable form will not function properly otherwise. 6. Photometry Now that all of the various dialogs and options/parameters have been discussed, it is time to go through the actual photometry procedure. This will entail starting CCDPHOT (with optional arguments), verifying parameters, constructing a template, then finally doing the photometry on a set of objects. 6.1 Starting CCDPHOT As noted in the beginning of this HOWTO, CCDPHOT _must_ be run from IDL started in a C-shell. Again, the procedure follows: ...]$ csh ..~]$ source /usr/rsi/idl_5.2/bin/idl_setup ..~]$ idl . . . IDL> ccdphot The csh command puts you in a C-shell, the source command sources the proper IDL setup file (if it wasn't sourced automatically), the idl command starts IDL (of course), and the ccdphot command starts CCDPHOT. This is the typical way to start it. After IDL compiles a bunch of CCDPHOT modules, you will be presented with the CCDPHOT dialog box. From here you can load a FITS image. If the date, JD, or filter are incorrect in the Image Parameters dialog, a keylist must be used. An example keylist file is given below: AIRMASS K AIRMASS DATE K DATE-OBS DATETMPL T YYYY-MM-DD EXPDELTA V 0.0 EXPTIME K EXPTIME FILTER K FILTNAME FILENAME K CCDFNAME OBJECT K OBJECT UT K UT The first column is the keyword as CCDPHOT knows it, the second is a code for what the the following column value represents (K, for Keyword, T, for Template, or V, for Value), and the last column is the FITS keyword, template, or value of the corresponding CCDPHOT keyword in the first column. The ones that are typically needed are DATE, DATETMPL, and FILTER, but this list should be used in its entirety with only the necessary keywords modified. To use the newly created keylist, CCDPHOT should be started like so: IDL> ccdphot,keylist='200205.key' where 200205.key is an example file name with the above contents in the current directory. If the file is elsewhere, the relative or absolute path must be given. 6.2 Verifying Parameters Once IDL finishes compiling a bunch of CCDPHOT modules, the main CCDPHOT dialog opens up. From here you can load an image by using the "Select File" dialog. Once selected, the image will be loaded into the Itool window. This is where most everything else is accessed. From the Itool window, select the "Image Params" button to open the Itool Image Parameters window. Check in here to make sure all the values are being read properly into CCHPHOT. Typical errors would be: missing or wrong Filter code, incorrect Date of observation, and bad Julian Date (e.g. 172xxxx instead of 245xxxx is very common). Check the FITS header keywords and use a keylist to tell CCDPHOT the proper keyword names. In order to load the new keylist, CCDPHOT must be restarted as shown above. Once all the image parameters are being read in properly by CCDPHOT, open the Itool Photometry Parameters window by clicking on the "Photometry Params" button in the Itool window. Using the plate scale, determine the proper aperture radius in pixels (section 4.3). Remember that the aperture is entered as a _radius_, not a diameter. Set all the other values appropriately, remembering to set the plate scale to 1. Once the values are entered, they can be saved by entering a name in the file name text field (followed by a carriage return), then pressing the "Save" button. Similarly, previously saved photometry parameter files can be loaded with the "Load" button. NOTE: both of the above windows can be hidden with the "Dismiss" button. 6.3 Constructing a Template Once the image and photometry parameters are all correct, it is time to create the template. To do this, open up the template manager by clicking on the "Template Mgr" button in the Itool window. Select the "Add Template" button and enter a name for the new template in the dialog box that pops up. The name is typically the object name. Upon hitting , the new template name appears in the Template Name List. Select it to bring up the Add/Activate window. Now is the time to create the actual template. This is done by left- clicking on the objects in turn (object, check1, check2, checkA, etc.). As each object is clicked, an entry with the reference number (0 to n), , X- and Y-position is added to the Add/Activate window's main field. Once all the objects are chosen, they need to be named. Just click on each line in turn, then type a new name in the "Change name of selected object:" text field, followed by a carriage return. The first object should be the name of the object of interest (all lower case with no spaces), and the check stars should be in ascending order, numbered then lettered comparison stars. An example is listed below: 0 198.000 592.000 1 248.000 445.000 2 264.000 412.000 3 225.000 289.000 4 219.000 274.000 becomes: 0 pks1510-089 198.000 592.000 1 check1 248.000 445.000 2 check2 264.000 412.000 3 checkA 225.000 289.000 4 checkB 219.000 274.000 Remember: the comparison stars MUST be of this form. If they aren't, the script "pegasort" will not function properly. Once the template is finished, it can activated by pressing the "Activate" button. This is the configuration when performing photometry. DO NOT DISMISS EITHER OF THESE WINDOWS. The template can now be saved in the usual manner. Likewise, an already created template can be loaded. 6.4 Photometry Walk-Through When the image and photometry parameters are all set and the template activated, photometry can be performed. To commence photometry on a field, left-click on the anchor object. This is the first object in the template which has the reference number of "0". CCDPHOT now calculates the instrumental magnitudes (in addition the FWHM, peak counts, etc.) for all the objects in the template and writes them to the .log file. It then calculates the new position of all the objects in the template (using the location of the peak counts as the center) and compares them to the previous values. If any one object moves too much, CCDPHOT assume something is wrong and issues a warning. The choices to clear the warning are "Ignore, avoid template corruption" and "Accept new object locations". You should ALWAYS ignore! If you don't you may end up doing photometry on a cosmic ray hit or some other nearby star in the field. If this error comes up all the time, you can try to create a new template, reduce the "Local box maximum radius" in the Photometry Parameters window, or select "Use exact position" in the same window. These should be tried in the order listed and the last should only be used if all else fails. The last option is undesirable due to the care required when clicking the anchor object. Once the template is accepted (i.e. no more errors when the anchor is clicked), the "Auto" button in the CCDPHOT window can be pressed and CCDPHOT will perform photometry on each frame in turn. Once the Auto button is pressed, a dialog box comes up asking to "Stop on Last" or "Set Stop Point". The usual selection will be Stop on Last since all the files in a particular directory need to be done. If the Auto option is not desirable for some reason, "Next" can always be selected instead to move through the the files in the directory. If this is done, the anchor object will need to be clicked in each frame. 7. Conclusion Once a .log file is finished, it will typically need top be sorted. At present, there is only one easy way to do that: using the pegasort script. In order to use the script, the .log file can have only one object in it, that object name must be consistent, and there should be only one set of entries per frame. The only action which causes multiple entries per frame is clicking on the anchor object more than once. If the pegasort script complains about multiple entries, check the .log file for them. After the .log file is sorted into a .txt file, the data contained within can be plotted with the "pegaplot" script. This script provides a quick look at the data and can even produce publication quality graphs if use properly. See the PEGA-Data-Processing-Tips-HOWTO for descriptions of the pegasort and pegaplot scripts, and for other very useful information. That HOWTO is accessible on the AstroNet system by typing "pega-info" at any prompt, and this HOWTO is accessible by typing "ccdphot-info" at any prompt.