A PRIMER FOR DAOPHOT II AND ALLSTAR

by Bill Harris (April 2002)
and further extended by Helmut Jerjen

DAOPHOT is the umbrella term for a suite of software written by Peter Stetson (HIA/NRC Canada), designed to do stellar photometry on digital images. It's specifically aimed at doing high quality photometry on crowded fields, and was developed in stages by Stetson from the mid-1980's through the 1990's. Several other codes for digital photometry are available now around the world, but DAOPHOT still holds something of the status of the "industry standard" and is the one that almost everything else is compared to.

A complete version of DAOPHOT and its companion code ALLSTAR is embedded within IRAF and can be learned through the usual IRAF protocols. However, Stetson's original version is a standalone set of Fortran codes, which is linked to IRAF only through its use of the same .imh image format. The standalone version has several advantages over the IRAF version:
  1. it runs faster
  2. it's easier to learn
  3. it's more flexible (e.g., several PSF models to choose from)
  4. the output files are much simpler and cleaner to read, and to feed into your follow-up reduction programs
  5. at the coding level, it's guaranteed to follow Stetson's deeply thought out principles for doing psf-fitting photometry.
Finally, a very important feature of DAOPHOT - which actually does mean a lot once you start using it - is that it is "astronomer-friendly" as opposed to computer-programmer-friendly. It's clear, logical, fast, and you will get used to it in no time.
This primer is intended as a quick and easy introduction to DAOPHOT and ALLSTAR. There's a more extensive manual , written by Stetson, which is very useful once you've had one or two first run-throughs. What I've written below is intended to guide you through a basic, first-time use of the code.
This will take you half an hour or less. Ready? Here we go:

THE IMAGE

Suppose that you have a CCD image in hand, which I will refer to below as "frame1.imh". The image needs to be in IRAF *.imh format; if you originally had it in FITS format, then just convert it with the IRAF dataio/rfits routine or even simpler use the imcopy command ( imcopy frame1.fits frame.imh). If it's in HST *.hhh format, again convert it to .imh from within STSDAS.
You first need to know a few basic things about your image:
  1. Is it an average, median, or sum of several individual frames? If so, how many?
  2. What is the mean FWHM ("seeing") of the star images on the frame? (the IRAF/imexamine task is handy for this.)
  3. What are the readnoise and gain (e-/adu) of the image (or if it's an averaged image, what was the readnoise and gain of a single exposure)?
  4. What is the maximum intensity value (in adu) at which the pixels start becoming nonlinear, or saturate?
  5. What is the minimum intensity value below which the pixels should be ignored (cold pixels, defects, etc.)?
With these numbers in hand, now go on to defining the parameter tables:

THE THREE PARAMETER TABLES

Standalone DAOPHOT uses three little tables of parameters called

daophot.opt
photo.opt
allstar.opt

You need to have copies of these IN THE SAME SUBDIRECTORY THAT YOUR IMAGES ARE STORED. They are tiny, so it's easy to keep as many copies as you need in all your image subdirectories. Here are generic versions of them, which can be copied to get you started:
daophot.opt
FWHM=1.7 fwhm of psf profile (pixels)
FIT=2. psf fitting radius (pixels)
PSF=11. psf box size (pixels)
READ=5.00 readnoise, in adu
GAIN=7.0 CCD gain (e- per adu)
TH=3.5 detection threshold in sigma(sky) units
AN=1 analytical PSF model choice (Gaussian, Lorentz, ...)
LOWBAD=10 low-cutoff bad pixel threshold in sigma(sky) units
HIBAD=30000 high-cutoff pad pixel threshold in adu units
WATCH=0 level of output to screen
VAR=0 variable psf level

This table gives the numerical values of several quantities used in many places throughout the DAOPHOT subroutines. The meanings of most of them should be fairly obvious from their names. The psf itself will be defined as a fiducial star image within a square box of "PSF" pixels width (11 x 11 in the above example), but the only part of the psf used to determine the fit to each star is the part within the central radius "FIT" (2 pixels in the example). The outer parts of the psf are used to fit the wings of neighboring stars.

Note that READ (the readnoise) is expressed in adu, not e-.
The threshold TH is in units of the standard deviation of the sky noise. DAOPHOT does its own estimate of the mean sky level; you just need to specify the number of sigma's above sky that you want to use.
Similarly, LOWBAD (the lower bad-pixel threshold) is expressed in sky-sigma units (10 standard deviations in the example above). Make it generously large.
AN refers to DAOPHOT's ability to use different analytical psf models. It defines the psf numerically, as a sum of an analytic function and a table of residuals. See the manual for more, but the bottom line is that this approach gives it unique power to handle a huge range of situations.
Finally, VAR allows you to make the psf be a constant (the same everywhere across the frame); a linear function of x and y; or a quadratic function.

Some practical advice (based on considerable experience!):
  1. FIT should be equal to or a bit bigger than FWHM, for optimum photometry.
  2. PSF should be 3 or 4 times bigger than FWHM (far enough out that the wings of the psf have dropped to near-zero intensity)
  3. TH should be no less than about 3.0 or 3.5, unless you are *really* interested in digging into the noise and thus inevitably getting lots of false detections,
  4. To choose AN: Values from 1 to 6 are allowed. AN=1 is a Gaussian analytic function and works quite well for normal ground-based CCD images that are spatially well sampled. AN=4 is a Lorentzian function, and works well for HST/WFPC2 images. You can also choose Moffat and Penny functions; see the manual.
  5. Even if you think the psf changes across the frame, always start by trying VAR=0 (constant psf) and see what the results look like. The more complicated the psf model gets, the more stars across the frame you will need to define it.

photo.opt
A1 = 3 radius of first (smallest) aperture, in pixels (will be used for the phot zero point, see p.26 of manual)
A2 = 0 radius of second aperture
A3 = 0 etc.
A4 = 0
A5 = 0
A6 = 0
A7 = 0
A8 = 0
A9 = 0
AA = 0
AB = 0
AC = 0
IS = 15 inner radius of sky annulus
OS = 20 outer radius of sky annulus

This table sets the radii of the apertures used to do aperture photometry. Usually you will want the first (smallest) one to be about equal to FWHM. You can define up to 12 apertures, useful for working on curves-of-growth, but any apertures after the first "zero" one are ignored. Fractional aperture radii (2.5, 6.3, etc.) are allowed.
allstar.opt
fit = 3.0 psf fitting radius
isky = 15. inner sky annulus radius
osky = 20. outer sky annulus radius
watch = 1.0 level of output to screen
redet = 1 redetermine centroids?

These are the parameters used by ALLSTAR, which is the code that actually does the simultaneous, nonlinear, iterative fit of the psf profile to all the stars in the frame simultaneously. The only parameter different from daophot.opt is "redet": do you want the (x,y) coordinates of the stars to be free parameters in the fit (redet=1), or not (redet=0)? Normally you'd choose redet=1 because it gives the best quality of fit for that particular image. However, maybe you have external information giving more exact object centers, in which case you would use redet=0, and ALLSTAR would then adjust only the psf amplitude to do the fit.

A final note on the tables: there are other code parameters in addition to the ones in the examples above. These are all listed every time you start up DAOPHOT, and you can change them too just by adding them to the tables. However, these others tend to be much more subtle things that you should tinker with only in rare conditions. My advice for these: just go with the default values.

RUNNING THE CODE: THE BASICS

Now you are ready to start the code. Here's a straight run-through of the basic sequence of steps.
  1. Start up IRAF, open an image display window, and load the image frame1.imh into the window. It's useful to have it side by side with your daophot window so that you can go back and forth between them.
  2. In another window, start up DAOPHOT: from your directory containing the image and the three *.opt files, type daophot and you are in. After printing out the full daophot.opt file (including the "other" parameters not explicitly listed in your table, but described in the manual), it prompts "Command:" and waits for your answer.
  3. ATTACH the picture by typing in attach frame1.imh (or equivalently, just attach frame1 as the .imh extension is assumed). Check that it's read the right picture dimensions from the image header. NOTE: currently the maximum allowed array size is 2048 x 2048. This is hardwired into the code. To increase it, you would have to get into the source code and recompile it.
  4. FIND stars: type in find and answer the questions that it gives you. For example, suppose that "frame1.imh" was the average of three individual exposures. Then to the query "Number of frames averaged, summed:" you would answer: 3,1
    The program then finds all stars with any pixels brighter than the detection threshold given by TH. The list goes into a file called frame1.coo unless you specify a different name. To the query "Are you happy with this?", answer "yes" unless you want to temporarily change the threshold and run it again.
    Take a look at the *.coo output file. Its organization is typical of the daophot file structure -- see the Manual for a detailed description of what each column means.
  5. Do aperture PHOTometry: Now type phot and measure all the stars in the *.coo list through the list of apertures given in photo.opt. To the prompt PHO> just hit Return and continue. (If you temporarily want to change the aperture radii for this specific run, however, you can enter A1=4 (for example) to change A1, IS=22 to change IS, etc.) The results will go into a file "frame1.ap" unless you specify another name for it.
  6. PICK some candidate psf stars: Now type pick which will go through the *.ap list and find some "decent" candidate stars. Tell it how many to look for -- for a start, try 20. The candidates are stored in a file frame1.lst and a list of their neighboring stars (i.e., other stars within a radius PSF of the candidates) are stored in another file frame1.nei You can inspect these files later if you want to know where and how bright all these candidates are.
  7. Define the PSF: Now it's time to build the point spread function. First, type opt to get the parameter table back again. At the prompt OPT> type: wa=1 ("watch progress". For most of the subroutines, wa=0 is suitable because you don't want a whole bunch of stuff dumped onto the screen as the functions FIND, PHOT etc. do their jobs. However, for the PSF function, you need to have the higher-level wa=1 set because it will put out very useful little contour maps of each psf candidate star for you to inspect.)
    When you've done this, at the next OPT> prompt hit Return to get the Command: prompt back again.
    Now type: psf and go ahead. The actual psf file (which is the map of residuals after subtraction of the analytical function -- Gaussian or whatever you chose) is stored in a file frame1.psf (again, unless you give it a different name).
    Each candidate star will pop up as a little pseudo-grey-scale map. If you don't like the looks of it (crowded? nonstellar? too near the edge of the frame? brightest pixels saturated?) then answer "n" to the query "Use this one?" If it looks OK, answer "y" and go to the next one. Throwing out bad candidates can be done very quickly and effectively this way.
    You can get a better look at each candidate of course by using your IRAF display window. Going back and forth to it is sometimes helpful.
    If you are using a constant psf (VAR=0) then try to pick at least 10 stars spread across the frame. If you are using a linear variation (VAR=1) then you'll need 20, 30, or more stars spread well across the frame, and if you are using a quadratic variation (VAR=2) then you'll need still more. However, you might want to think of throwing away your data if the variation is really that bad :-(
  8. EXIT the program: You are now done with the steps of finding stars and defining the psf. exit
  9. Run ALLSTAR: Now start up the psf-fitting code by typing: allstar and it prints out the full table allstar.opt for your inspection. You can temporarily change any of the parameters from the OPT> prompt if you want. If everything's right, then hit Return and go on.
    Enter the image name (frame1.imh), the psf file (frame1.psf), the aperture photometry file (frame1.ap), the file for the output data (the default is frame1.als ), and the name for the "subtracted" image (that is, the final reduced image with all the psf-fitted stars subtracted away from the picture).
    From here it's all automatic, so just watch it run. The little "in progress" table written on the screen for your enjoyment will give for each iteration the number of input stars, the number of stars rejected, and the final number of successfully fitted stars.
    Take a careful look at the *.als output file: it's the one you will be using later on to generate "final" calibrated photometry, so understand what each column is. For each fitted star it lists a running ID number, x, y, magnitude, error, local sky value, number of fitting iterations, chi, and "sharp" (see the Manual).
  10. Inspect the results. There is now a new image (frame1s.imh; the "s" suffix is added to the original image name) stored in your directory, which is the subtracted picture. In your IRAF display window, load it, and then blink back and forth between the original picture and the subtracted picture. If all went well, the stars in the fitted starlist should have "vanished" fairly seamlessly, except perhaps for some very bright ones that may be partially saturated or noisy, or maybe some slightly nonstellar things that left little "doughnuts" behind.
    If the subtracted picture doesn't look very good -- blotches and spots all over the place -- then it probably means the psf wasn't valid. Go back into daophot and rebuild the psf with a different or longer list of candidate stars.
  11. Clean up your files. The ones you'll want to keep are [frame1.psf] and [frame1.als], once you are happy with the results. The intermediate files (*.coo, *.ap, *.lst, *.nei, and the subtracted picture) can usually be deleted.
    All of the files can be regenerated if necessary. For example, if you wanted to keep the aperture photometry, then run PHOT again, with the *.als file as the input file. The daophot file structure is simple and repetitive, so the output from one subroutine can be used as the input to another one in many ways.
And that's the end of the basic sequence of operations. You will find that FIND, PHOT, PICK, and PSF run very quickly. ALLSTAR is the most time-consuming, but it can still do several thousand stars in a few minutes on a normal (rather slow) Sun/unix system. With fast processors and lots of memory (256 Mb or more) it will race through thousands of stars in a few seconds. It's best to gain experience with daophot in its normal, interactive mode. (NB: It's particularly important to be "interactive" in the PSF-definition step!! Getting a good, clean psf is the key to everything else. The other steps are more routine.) But if you want to run all of this in batch (non-interactive) mode, just make up a file which has your typed-in commands to the daophot sequence of steps exactly as you would use them in the interactive mode, and then run that command file.

OTHER USEFUL SUBROUTINES IN DAOPHOT

After becoming familiar with the basic sequence, you will want to use some of the other subroutines in the daophot package. Read about them in the manual. Usually the first ones to look at are:
There is a very useful routine SORT for sorting any of its output files by x, y, magnitude, or any other column of data you want. Another routine, APPEND, puts two files of the same type (*.ap, *.als, etc) together under one header.
SUBSTAR: this will take an input image (frame1.imh) and the psf-fitted photometry data (frame1.als) and do the star-subtraction. It's useful if you accidentally deleted your subtracted picture, or if you want to compare the results of different .als files, or if you just want to subtract part of the list (e.g. the 100 brightest stars, or something like that).
ADDSTAR: this will add "fake" stars (scaled psf's) to your picture -- either from a random number generator, or from your own specially constructed file. ADDSTAR is your entry into doing artificial-star experiments to find out more than you ever wanted to know about the measurement uncertainties, detection completeness, and so on.

Happy measuring!