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).