Aperture photometry using APT

Downloading, Installing, and Starting the Software

APT = Aperture Photometry Tool. Russ Laher wrote it, and it can be downloaded here. Follow the directions there to install it. You may be interested in the Unix cheatsheet. If you're using windows, see the windows hints, tips, and tricks page. (run apt java -mx512M APT)

For a comprehensive introduction to APT, please see this page. The stuff that is here on the wiki is more skeletal, and is meant to be a quick overview with a focus on what you need as a NITARP user of APT. As of May 2010, two papers on APT have been submitted to PASP: http://spider.ipac.caltech.edu/staff/laher/apt/paper1.pdf (overview of APT) and http://spider.ipac.caltech.edu/staff/laher/apt/paper2.pdf (validation using real data). You may be interested in these more detailed discussions.

Loading an image

Click on "Get image" and load an image. It will come up with a default stretch. You can use the buttons and fill-in boxes to change the stretch (limits and scale) if desired. You can obtain a histogram of the values in the image by clicking on the "image histogram" button.

Picking an object, Doing the photometry, and Exploring the options

Use your mouse, scroll around in the image in the upper right, and find an object you wish to measure. Click on the object. In the lower center of the APT window, it gives you a greatly magnified version of the portion of the image you are investigating. You should use this zoom-in to try to center your object on the mouse cursor as accurately as possible - the better your initial guess, the easier it will be for the computer to correctly centroid the object.

The program did the photometry using its default values. The centroid radius (e.g., the max offset that it can calculate the centroid from your initial guess), the aperture radius, and the sky annulus parameters (inner and outer sky radius) are all set to particular values by default. They are in units of pixels. To figure out what these values are in arcseconds, look at the FITS header for your image. Click on "FITS header" (top center), and find CDELT1 or CDELT2. These are the numbers of degrees per pixel. Convert this value to arcseconds by mulitplying by 3600 arcseconds/degree. Make sure that the aperture and annulus parameters are what you want them to be. (See this page for more discussion.)

IMPORTANT: By default, the current version of APT does NOT subtract off the background in the photometric calculation. You must enable background subtraction manually by clicking on the "More Settings" button and selecting the appropriate sky algorithm. Once background subtraction has been enabled and you have clicked on the "Recompute Photometry" button, the "Curve of Growth" plot will show the nice asymptotic behavior that you might expect.

You can use the following buttons to further explore your choice of aperture and annulus size. In each case, the aperture and annulus sizes are indicated, along with its calculated background level:

• aperture slice - one-dimensional slice through the aperture. Allows you to investigate if the source is resolved or saturated, and if APT automatically "snapped" the aperture to the correct centroid location. Sometimes humans can do a better job than the computer. A correctly centered aperture will have aperture slice that peak at zero (or nearly so).
• curve of growth - how the total flux measured changes as a function of aperture
• source scatter - range of pixel values within the aperture -- you can explore the effects of too large or small an aperture here.
• radial profile - circularly averaged slice through the aperture. The PSF is often roughly circularly symmetric, so this allows you to explore the placement of the annulus (is it on top of the Airy ring?) and the level of the background more easily than the aperture slice option above. This also allows you to investigate whether the source is resolved or saturated.
• sky scatter - range of pixel values within the sky annulus -- you can explore the effects of too large or small an annulus, or the influence of nearby sources or nebulosity, here.
• sky histogram - histogram of pixel values within the sky annulus -- you can explore the effects of too large or small an annulus, or the influence of nearby sources or nebulosity, here.
• hide/show aperture - should be obvious what this means!
• color table toggle - changes the color table

If you change any of the values, you will need to ask it to 'recompute photometry' (button in the lower left). Changes in the requested aperture/annulus will be reflected in the display indicating the size of the annulus/aperture in the lower right, as well as in all the popup graphs you can get from clicking on the buttons described above.

The results of the photometry are reported under "RESULTS" in the lower left. Note that it recognizes the units of your input image (MJy/sr, DN, whatever) and reports the photometry in the same units. Review the information on Spitzer units, specifically as it applies to units of Spitzer images. In order to get it to report the photometry in Jy, instead of MJy/sr, you will need to derive the appropriate image data unit conversion factor, and corresponding reasonable units after conversion -- there's information on this on the Units page. Then go to "more settings" and enter those values in the corresponding boxes. If you click the "perform image data conversion" box, it will report the photometry in Jy (or whatever unit you want) on the main screen.

You can manually keep notes on the photometry you are calculating, or you can click the button that says "save results" to write the values for this object to a file. If you click on "show results", you can see the file it's accumulating. "Plot results" allows you to explore the distribution of results so far. If you have done this before, you may want to execute the top-menu function File > Clear Photometry File before starting lots of photometry so that you get just the new photometry in this file.

You can also find, under the top-level menus, a way to save user preferences that were set up in your APT session. By default, preferences are saved in hidden directory ~/.AperturePhotometryTool in a file called APT.pref, and automatically loaded from this hidden file when a new APT session is started.

You should experiment enough with this tool to develop some intuition about what the various parameters do -- aperture and annulus are the two big ones to play with. How does the flux from a bright star change as you change the aperture, holding the annulus constant? A faint star? As you change the annulus (keeping the aperture constant)? Why does it do that? You can even make some plots interactively within APT -- the "curve of growth" refers to how the photometry changes as your aperture changes. For some of the other tests you might be able to devise, you might have to get into something like Excel to make some plots.

After you have settled on the aperture/annulus that works for your targets, if you have pre-assembled a list of objects whose RA/Dec or image pixel coordinates you already know, you can submit a list of targets to APT and have it do all the photometry on all the objects at once. Click on "source list" on the upper left to load a file. You have to tell the computer whether you are giving it pixel coordinates or RA/Dec. Caution -- pixel coordinates MAY NOT BE THE SAME between images, but RA and Dec (for the same objects) better be the same! Note that you will have to change the scale factor separately for each band, so you can't just load an image, load the source list, and be off and running. Think carefully about what you are doing. It's really easy to shoot yourself in the foot here. Take the photometry you get out with a grain of salt until you convince yourself it is right. Make some plots. Do they look like you expect? Do you get the same photometry as your neighbor, within errors?

Also, note that APT has a batch mode that can be used in two different ways:

1. Display a FITS image : APT.csh myimage.fits
2. Display a FITS image AND automatically execute the source-list tool on it : APT.csh myimage.fits mysourcelist.txt

Prior to using APT's batch mode, you MUST save user preferences in the default location for the way you want the image displayed and the source-list tool ran (there are various available options).

Looking for a cookbook?

Ain't gonna happen, guys, 'cause this is real science, so there's no answer in the back of the book. If there was no part of this that required thinking and judgment, I could write software to have the computer do the whole thing from start to finish. You do need to think, all the time. BUT, here are some guidelines.

YouTube video on all of this

1. Download and install APT.
2. Load an image into APT. View the FITS header. Get the CDELT values, or whatever pixel scale it is (may also be "PXSCAL" which is pixel scale, or platescale). Really read the header and comments, and apply your brain. You're looking for a conversion between pixel scale and angle on the sky. These should be in "degrees per pixel" or "arcsec per pixel", something like that. If you can't find that, can you find a number close to that which you can convert into this? (e.g., did they provide pixels per arcsec?)
3. Start up a spreadsheet to do calculations.
4. Follow the instructions on the Units page under "getting the number APT needs" (near the bottom of the page). Do the calculations in multiple steps in your spreadsheet so you can check for errors. Watch your units.
5. Check your calculations with a friend. Are you getting the same numbers? CAUTION: the numbers for IRAC and MIPS will not be the same!
6. Back in APT, put this value in the conversion value under the "more settings" button (lower left of main APT window)
7. In APT, turn on background subtraction in more settings (option B)
8. Apply settings. Close window.
9. Change settings to the right aperture and annulus. Spend some time exploring this so that you know what is going on, but when you're ready to work for real, use the apertures below.
10. You can put in the aperture correction in APT (under "More settings") here, but be careful to use the right number! (See below.) If you are absolutely sure you know what you are doing, this is an easy way to get valid photometry out right away. However, I don't think I have ever done photometry just once. If you do fewer calculations within APT, and more later in the spreadsheet, it is less likely that you will have to redo absolutely everything in the end. The labor intensive part is measuring the fluxes. It's easy to tell Excel to multiply columns of numbers. If you aren't sure if you used the I2 aperture correction when working on the I3 image, you'll have to go back and do it again. If you don't do an aperture correction in APT but instead do it in Excel later, you can easily check/redo your multiplication. Just sayin'.
11. If you want, save your user preferences for your next APT session. You can also save/restore user preferences in separate files for different images/bands, but remember that APT ONLY automatically loads user preferences from hidden file ~/.AperturePhotometryTool/APT.pref, so you will have to explicitly read in the user-preferences file you want for the image you are working on.
12. Do photometry (click on object, recenter, calculate or recalculate values). (If you know the x,y position of your source, rather than struggling to find it on the image, you can type the pixel location into the pixel boxes in APT, but do NOT hit 'snap' (yet), just hit 'recalculate photometry'. Then 'snap' again, and 'recalculate photometry' again.)
13. In another Excel spreadsheet (or tab), write down "source_intensity (sky-subtracted)" because this is the sky minus the scaled background from the annulus. Check your units. Make absolutely sure you understand what you are doing.
14. Repeat for each object of interest in each band of interest, or create a source list and pass that to APT once you are sure of your parameters.
15. If you didn't do this within APT, in your spreadsheet, multiply measured fluxes by aperture correction (band-dependent -- see below). Be careful that it matches the band you're using!
16. In your spreadsheet, use the zeropoints to calculate magnitudes. (Follow the instructions on the Units page, under 'magnitudes'.)
17. Compare with other people's results. (It may be easier to compare with other people's magnitudes rather than flux densities, because the numbers are smaller.)

Apertures, sky annuli, and aperture corrections. See Photometry pages for explanation of what this is and why you need it. The aperture corrections are intimately related to the aperture and annulus you used, compared to what the teams used to calibrate the instrument. Which choice you make (from a variety of options provided by the instrument teams) is intimately related to the kind of data you have, whether they are crowded or complex or relatively clean (see note below).

• IRAC. These are listed by the instrument team in terms of NATIVE PIXELS. The one that Luisa has had the most luck with is the native pixel aperture 3 px, annulus 3-7 px combination, because she works in regions with complex structure (see note below). Note that the images from the pipeline resample to half the native pixel size, so this corresponds to 6, 6-14 px in the resampled mosaics, which is what you're using. If you are using that combination of aperture and sky annulus, the aperture corrections for the four IRAC channels are 1.124, 1.127, 1.143, 1.234, respectively. Operationally, this means, using IRAC-1 as an example, that the 6/6-14 combination misses 12.4% of the flux, so take the flux you measure using 6/6-14, and multiply it by 1.124. Do the same thing for the rest of the channels accordingly. For other aperture/annulus combinations, check the IRAC Instrument Handbook for the other options.
• MIPS. These are listed by the instrument team in terms of ARCSECONDS. The pixel scale of the MIPS-24 pipeline mosaics is 2.45 arcsec per pixel. The instrument teams list a variety of combinations, but I suggest trying 7"/7-13" and 7"/20-32" to see what you get. That works out to be (check me!) 2.85/2.85-5.3 and 2.85/8.16-13.06 px. APT (last I checked anyway) doesn't take fractional pixels for these parameters. So round it. 3/3-5, 3/8-13. (I expect the latter to match the PSF fitting photometry [which is what I did] a little better because the values are closest to integers.) The aperture corrections for these two combinations are 2.05 and 1.61, respectively. For 70 microns, if anyone actually gets into this, see the MIPS Instrument Handbook for the real values.

Rebull 12:46, 25 May 2011 (PDT) -- NOTE on this choice of aperture for IRAC (in star-forming regions like the BRCs or CG4 or other similar regions), because Russ asked last year and I gave him a weaseley answer because I'd forgotten exactly why, and then I just spent 2 days rediscovering the reason ... In this region, and star formation regions in general, there is a LOT of structure in the background and a lot of variation in the sky level. You want to sample the sky as close to your star as possible, because otherwise you end up including in your sky estimate pixels that are of different brightnesses. This results in a lot more scatter in the CMDs. To prove this to yourself, do what I just did -- Do photometry on the same suite of stars in all four bands for 3, 3-7 and 3, 12-20 (another recommended sky/annulus combination from the IRAC team). Go check and use properly the aperture corrections for these two different combinations for the 4 channels. Then, the only difference between your photometry will be the size of the annulus. Plot the photometry obtained with one annulus ("method 1") against that from the other ("method 2") -- you will need to plot either log(flux densities) or magnitudes. Try also (meth1/meth2) vs. (log) meth1 or some other combination that highlights the differences in the photometry (hard to see if just plotting meth1 vs meth2). Can you see differences, especially at i3i4, where the sky brightness is the most variable? Try some CMDs too. I find a LOT more scatter in the plots using the larger sky annulus.

Other Contributions

One of the students from a 2008 team developed File:APTtutorialpresentation.pdf, which is a very nice APT tutorial presentation, which may be helpful.

One of the 2010 teams developed APT Tutorial for Educational Poster, which may be helpful.