README_apex_user_list_081108 TABLE OF CONTENTS 1. OVERVIEW 2. POINT-SOURCE FITTING ON A USER LIST (BEST-FIT POSITIONS) 3. THE USER LIST 4. USAGE 5. NAMELIST 6. DETERMINATION OF NEARBY SOURCES 7. WARNINGS FOR POINT-SOURCE FITTING ON A USER LIST 8. APERTURE PHOTOMETRY ON A USER LIST (EXACT POSITIONS) 9. ACKNOWLEDGEMENTS 1. OVERVIEW It is sometimes desirable to input a list of positions to a photometry program and have it find the flux of a source at that position. For example, the input positions could come from a shorter wavelength where the signal-to-noise is higher. We'll call this "User List" mode. We are developing a new APEX functionality to allow the user to input positions of objects in the frame instead of using the current Detect module. However the code is still experimental. With some limitations discussed below, APEX will do PRF fitting and aperture photometry on the input list. However it is important to note that in the current Perl script versions, the positions of objects will be allowed to move within a small radius as part of the fitting. PRF-fitted and aperture fluxes will be for that (possibly shifted) position. Note also that APEX will not search for additional objects, so if any are missing then proper deblending cannot be done. The functionality is available in MOPEX 18.1 as a beta release. It is available for users to try, but support will be minimal until a later release in 6-12 months. The "apex_user_list" scripts will execute the new functions in place of the usual "apex" scripts. NOTE ON APERTURE PHOTOMETRY: As stated above, in the "apex_user_list" scripts, aperture photometry is currently performed on the newly measured positions. If the user prefers to measure aperture photometry with MOPEX on the user list positions without refitting, this is possible running the "aperture" module by itself. This is not as flexible with input as the "apex_user_list" scripts, but rather requires X and Y pixel positions. These can be created from a list of RA, Dec with MOPEX tools, but currently requires running additional modules and doing some hand-editing. These steps are described below for those needing this capability. All of these options are presently available only in command line. The current PRF-fitting version is in two new Perl scripts, apex_user_list_1frame.pl and apex_user_list.pl. Two example namelists will be found in the ./cdf sub-directory. 2. POINT-SOURCE FITTING ON THE USER LIST (BEST-FIT POSITIONS) In User List mode, the user's input table becomes the detection list. This is triggered by the presence of the keyword "INPUT_USER_LIST = user.tbl" in the namelist file, or the command-line option "-u" followed by the table in the call to the Perl script. A command-line entry takes precedence. There is also a variable in the scripts apex_user_list.pl and apex_user_list_1frame.pl called "use_input_list_type". This indicates the coordinates of the input list. There are also new optional parameters in the sourcestimate block: ANGULAR_DIST, and MAX_SHIFT_X, MAX_SHIFT_Y. Nearby sources for each input source are determined and fitted together in the sourcestimate module using the given ANGULAR_DIST (arcsec). Positions will move to "best-fit" values. Sources which are successfully fit but drift outside MAX_SHIFT_X, MAX_SHIFT_Y data pixels from the input position are flagged in the output table. The format of the output extract table is otherwise the same as before. 3. THE USER LIST The input table of source positions has to be in IPAC table format (see example below). A minimum of two data columns are required. Positions may be entered in sky coordinates, which are labeled with case-insensitive column names ("RA", "Dec"). These should have type "double" (d). This is the simplest way. Positions can be in pixel coordinates which are labeled with case-insensitive column names ("X","Y"), or by ("Global_X", "Global_Y"). In multi-frame mode, this is pixel position on the mosaic. These should have type "real" (r). The table may contain both sets of coordinates and other data columns. NOTE: The script will alter your input table, so make sure it is just a copy. 4. USAGE To run the single-frame point-source extraction using an input list: apex_user_list_1frame.pl -n apex_user_list_1frame.nl To run the multi-frame point-source extraction using an input list: apex_user_list.pl -n apex_user_list.nl 5. NAMELIST OPTIONS The namelist file is expected to be in the directory specified by the environment variable SIRTF_CDF, typically ./cdf. A new variable indicates coordinates of the input table: use_input_list_type = 1 A value of 1 indicates positions in RA, Dec with column names ("RA", "Dec"). The conversion program "s2c_trans" is used to convert the sky coordinates into pixel positions. Two additional columns are written out in the input table with column names "Global_X" and "Global_Y". In multi-frame mode, this is the pixel position on the mosaic. This is the simplest way. A value of 0 (the default) indicates pixel positions. In multi-frame mode, this is the pixel position on the mosaic. The column names in the input file are ("X","Y"). The conversion program "c2s_trans" is used to convert the pixel positions into sky coordinates. Two additional columns are written out in the input table with column names "RA" and "Dec". A value > 1 indicates that both types exist in the input table. Column names can be either ([X, Y], [RA, Dec]) or ([Global_X, Global_Y], [RA, Dec]). The new input parameter options in the namelist in the "sourcestimate" block are as follows: "ANGULAR_DIST" is the maximum angular distance (arcsec) used to identify the nearby sources for simultaneous fitting. If it is not given then the script will look for the Spitzer keywords "INSTRUME" and "CHNLNUM" in the input FITS header and the value gets set as follows: INSTRUME = "MIPS" and CHNLNUM = 1 ANGULAR_DIST = 6. INSTRUME = "MIPS" and CHNLNUM = 2 ANGULAR_DIST = 18. INSTRUME = "IRAC" ANGULAR_DIST = 2. for all four channels If the script is unable to set a value, the default is 0.0. In User List mode, the parameters Fitting_Area_X and Fitting_Area_Y which let the user define the fitting region are *required*. There are two more parameters MAX_SHIFT_X and MAX_SHIFT_Y (data pixels). If the fitted source position is greater than Max Shift away from the user-supplied position, the source is given a letter "O" in the deblend column (for "Outside"), along with any other letter flags. By default, these parameters are set equal to the fitting area dimensions. Typically, namelists will have a "select" condition that drops a source with an "O" in the deblend column. For multi-frame Apex in User List mode, creation of a detection map is required: run_detectionmap = 1. This creates "detectionmap.tbl" in the output directory. Once it is created, this can be turned off for subsequent runs. The block to run detectionmap in the namelist looks like: &DETECTIONMAP # N_Edge should have the same value as in SOURCESTIMATE below, N_Edge = 10, &END Also note that in this case the "InputType" parameter in the sourcestimate block should be set to "detection_map". These steps are needed to track the input source positions through the image stack. In the Apex namelists, both detect_medfilter and gaussnoise should be turned on to provide the ability to use background RMS for the point-source SNR. 6. DETERMINATION OF NEARBY SOURCES The input source positions are sorted first in Dec in ascending order. Bins are created in this sorted list using bin size = 2 * ANGULAR_DIST. The sources are again sorted in RA within each bin. Each input source position is then searched to find its distance from the other sources in the current bin and 2 adjacent bins on both sides. If this distance < ANGULAR_DIST, then the source is flagged as a nearby source and included in the fitting. 7. WARNINGS FOR POINT-SOURCE FITTING ON A USER LIST Care is needed when supplying a user list to Apex. If a source is not given in the user list, then Apex_user_list will not be aware of it. If it is bright enough and close enough to the source of interest, then Apex may not find a successful PSF fit and/or the flux of the source of interest may not be accurate. Even if all bright sources are listed, Apex is not determining blends by its usual method, but by a separation distance you give it. Some experimentation may be needed to find the best ANGULAR_DIST for your data. 8. APERTURE PHOTOMETRY ON A USER LIST (EXACT POSITIONS) For aperture photometry at given positions, make a mosaic of your data frames, if you have multiple frames. Start with sky coordinates directly in IPAC table format. Here is a simple example, input_list.tbl: |RA |Dec | |double |double | 274.072341 -2.544706 The next commands require you to have run the Mopex shell script, source mopex-script-env.csh. First translate the sky coordinates to pixel coordinates by reading the header of your mosaic image: s2c_trans -i input_list.tbl -o input_list_new.tbl -r mosaic.fits Note that it inserts pixel coordinates as 'Global_X' and 'Global_Y'. Using a namelist file in the cdf sub-directory, run the aperture binary stand-alone in command line: aperture -n cdf/aperture_input_list.nl Here's an example namelist, aperture_input_list.nl for a standard MIPS24 mosaic (aperture radii in 2.45" pixels): &APERTURE Input_Image_Filename = 'mosaic.fits', Input_ApUnc_Filename = 'mosaic_unc.fits', Input_List_Filename = 'input_list_new.tbl', Output_Table_Filename = 'aperture.tbl', X_Column_Name = 'Global_X', Y_Column_Name = 'Global_Y', HighPrecision = 1, N_Apertures = 3, Aperture_Radius_1 = 1.23, Aperture_Radius_2 = 2.45, Aperture_Radius_3 = 5.306, Use_Annulus = 1, Min_Number_Pixels = 10, Annulus_Compute_Type = 'mode', Inner_Radius = 8.16, Outer_Radius = 13.06, &END Ignore the warning from aperture about errorcodes. The output aperture.tbl will have pixel coordinates under Global_X and Global_Y. You can put in RA and Dec columns. Edit the two column headers from "Global_X" to "X" and from "Global_Y" to "Y". Keep the spacing the same. Then: c2s_trans -i aperture_edited.tbl -o aperture_new.tbl -r mosaic.fits And you will have RA, Dec, and your aperture photometry at the input positions. The fluxes in the output aperture.tbl will be in microJy, if the data are in MJy/sr or microJy/arcsec^2, otherwise they are in data units, i.e. it will assume pixel values are like counts. 9. ACKNOWLEDGEMENTS Apex was written for the SSC by David Makovoz. The current point source fitting User List modifications were written by Iffat Khan (SSC).