| qphot | noao.digiphot.apphot | qphot |
qphot -- quick aperture photometer
qphot image cbox annulus dannulus apertures
QPHOT computes accurate centers, sky values, and magnitudes for a list of objects in the IRAF image image whose initial coordinates are read from the image image cursor or the coordinate file coords , and writes the computed x and y coordinates, sky values, and magnitudes to the text file output .
The coordinates read from coords are assumed to be in coordinate system defined by wcsin . The options are "logical", "tv", "physical", and "world" and the transformation from the input coordinate system to the internal "logical" system is defined by the image coordinate system. The simplest default is the "logical" pixel system. Users working on with image sections but importing pixel coordinate lists generated from the parent image must use use the "tv" or "physical" input coordinate systems. Users importing coordinate lists in world coordinates, e.g. ra and dec, must use the "world" coordinate system and may need to convert their equatorial coordinate units from hours and degrees to degrees and degrees first.
The coordinates written to output are in the coordinate system defined by wcsout . The options are "logical", "tv", and "physical". The simplest default is the "logical" system. Users wishing to correlate the output coordinates of objects measured in image sections or mosaic mosaic pieces with coordinates in the parent image must use the "tv" or "physical" coordinate systems.
In interactive mode the user measure objects interactively with the image cursor, or select them interactively from the coordinate list coords . In batch mode the coordinates can be read directly from coords , or from the cursor command file specified by the parameter icommands .
If cache is yes and the host machine physical memory and working set size are large enough, the input image pixels are cached in memory. If cacheing is enabled and QPHOT is run interactively the first measurement will appear to take a long time as the entire image must be read in before the measurement is actually made. All subsequent measurements will be very fast because QPHOT is accessing memory not disk. The point of cacheing is to speed up random image access by making the internal image i/o buffers the same size as the image itself. However if the input object lists are sorted in row order and sparse cacheing may actually worsen not improve the execution time. Also at present there is no point in enabling cacheing for images that are less than or equal to 524288 bytes, i.e. the size of the test image dev$ypix, as the default image i/o buffer is exactly that size. However if the size of dev$ypix is doubled by converting it to a real image with the chpixtype task then the effect of cacheing in interactive is can be quite noticeable if measurements of objects in the top and bottom halfs of the image are alternated.
QPHOT computes accurate centers for each object using the centroid centering algorithm, pixels inside cbox and the default values of the centerpars parameters. Accurate sky values for each object are computed using the centroid sky fitting algorithm with histogram smoothing turned on, pixels inside the sky annulus defined by annulus and dannulus , and the default values of the remaining sky fitting parameters as defined in the fitskypars parameter set. Magnitudes are computed using pixels inside the apertures defined by apertures . The user must set the gain epadu to ensure that the magnitude error estimates are correctly computed and exposure to normalize the computed magnitudes to an exposure time of 1 time unit. The zero point of the magnitude scale can be adjusted by setting zmag . Airmass , filter , and obstime are book-keeping parameters. Setting them to appropriate values will simplify future analysis and calibration steps.
The following list of cursor commands are currently available.
Interactive Photometry Commands
? Print help
: Colon commands
w Save the current parameters
d Plot radial profile of current star
i Interactively set parameters using current star
c Fit center of current star
t Fit sky around the cursor
a Average sky values fit around several cursor positions
s Fit sky for current centered star
p Do photometry for current star, using current sky
o Do photometry for current star, using current sky, output results
f Do photometry for current star
spbar Do photometry for current star, output results
e Print error messages
m Move to next star in coordinate list
n Do photometry for next star in coordinate list, output results
l Do photometry for remaining stars in coordinate list, output results
r Rewind the coordinate list
q Exit task
Colon Commands
:show List the parameters
:m [n] Move to next [nth] star in coordinate list
:n [n] Do photometry for next [nth] star in coordinate list, output results
Colon Parameter Editing Commands
:image [string] Image name
:output [string] Output file name
:coords [string] Coords file name
:cbox [value] Width of the centering box (pixels)
:annulus [value] Inner radius of sky annulus (pixels)
:dannulus [value] Width of sky annulus (pixels)
:apertures [string] List of aperture radii (pixels)
:zmag [value] Zero point of magnitude scale (magnitudes)
:epadu [value] Gain (electrons per adu)
:exposure [string] Exposure time image header keyword
:airmass [string] Airmass image header keyword
:filter [string] Filter image header keyword
:obstime [string] Time of observation image header keyword
:radplot [y/n] Plot radial profile of object
The following commands are available from inside the interactive setup menu
using the i key.
Interactive Qphot Setup Menu
v Mark and verify the critical parameters (c,a,d,r)
c Mark and verify the centering box width
a Mark and verify the inner radius of the sky annulus
d Mark and verify the width of the sky annulus
r Mark and verify the aperture radii
In interactive mode the following quantities are printed on the standard output as each object is measured. Error is a simple string which indicates whether the task encountered an error condition from the centering algorithm, the sky fitting algorithm or the photometry algorithm respectively. Mag are the magnitudes in apertures 1 through N respectively and xcenter, ycenter and msky are the x and y centers and the sky value respectively.
image xcenter ycenter msky mag[1 ... N] error
In both interactive and batch mode full output is written to the text file output . At the beginning of each file is a header listing the current values of the parameters when the first stellar record was written. These parameters can be subsequently altered. For each star measured the following record is written.
image xinit yinit id coords lid xcenter ycenter xshift yshift xerr yerr cier cerror msky stdev sskew nsky nsrej sier serror itime xairmass ifilter otime rapert sum area flux mag merr pier perror
Image and coords are the name of the image and coordinate file respectively. Id and lid are the sequence numbers of stars in the output and coordinate files respectively. Cier and cerror are the error code and accompanying error message for the center computation. Xinit, yinit, xcenter, ycenter, xshift, yshift, and xerr, yerr are self explanatory and output in pixel units. The sense of the xshift and yshift definitions is the following.
xshift = xcenter - xinit yshift = ycenter - yinit
Sier and serror are the sky fitting error code and accompanying error message respectively. Msky, stdev and sskew are the best estimage of the sky value (per pixel), standard deviation and skew respectively. Nsky and nsrej are the number of sky pixels used and the number of sky pixels rejected respectively.
Itime is the exposure time, xairmass is self-evident, ifilter is an id string used to identify the filter used during the observation, and otime is a string containing the time stamp in whatever units the user has written into the image header or the otime parameter.
Rapert, sum, area, and flux are the radius of the aperture in pixels, the total number of counts including sky in the aperture, the area of the aperture in square pixels, and the total number of counts in the aperture excluding sky. Mag and merr are the magnitude and error in the magnitude in the aperture.
flux = sum - area * msky mag = zmag - 2.5 * log10 (flux) + 2.5 * log10 (itime) merr = 1.0857 * err / flux err = sqrt (flux / epadu + area * stdev**2 + area**2 * stdev**2 / nsky)
Pier and perror are photometry error code and accompanying error message.
In interactive mode a radial profile of each measured object is plotted in the graphics window if radplots is "yes".
In interactive and batchmode a radial profile plot is written to plotfile if it is defined each time the result of an object measurement is written to output .
If the object centering was error free then the field cier will be zero. Non-zero values of cier flag the following error conditions.
0 # No error 101 # The centering box is off image 102 # The centering box is partially off the image 103 # The S/N ratio is low in the centering box 104 # There are two few points for a good fit 105 # The x or y center fit is singular 106 # The x or y center fit did not converge 107 # The x or y center shift is greater than 1 pixel 108 # There is bad data in the centering box
If all goes well during the sky fitting process then the error code sier will be 0. Non-zero values of sier flag the following error conditions.
0 # No error 201 # There are no sky pixels in the sky annulus 202 # Sky annulus is partially off the image 203 # The histogram of sky pixels has no width 204 # The histogram of sky pixels is flat or concave 205 # There are too few points for a good sky fit 206 # The sky fit is singular 207 # The sky fit did not converge 208 # The graphics stream is undefined 209 # The file of sky values does not exist 210 # The sky file is at EOF 211 # Cannot read the sky value correctly 212 # The best fit parameter are non-physical
If no error occurs during the measurement of the magnitudes then pier is 0. Non-zero values of pier flag the following error conditions.
0 # No error 301 # The aperture is off the image 302 # The aperture is partially off the image 303 # The sky value is undefined 305 # There is bad data in the aperture
1. Perform aperture photometry interactively for a few stars in dev$ypix using the display and the image cursor.
ap> display dev$ypix 1 fi+ ... display the image ap> qphot dev$ypix 5. 10. 5. 2.,4.,6.0 ... move image cursor to objects of interest and tap space bar ... a 1 line summary will be printed on the standard output for each object measured ... type q to quit and q again to confirm the quit ... full output will appear in ypix.mag.1
2. Perform aperture photometry interactively for a few stars in dev$ypix using the contour plot and the graphics cursor. This option is only useful for those (now very few) users who have access to a graphics terminal but not to an image display server. Setup the task parameters using the interactive setup menu defined by the i key command as in example 1.
ap> show stdimcur
... record the default value of stdimcur
ap> set stdimcur = stdgraph
... define the image cursor to be the graphics cursor
ap> contour dev$ypix
... make a contour plot of dev$ypix
ap> contour dev$pix >G ypix.plot1
... store the contour plot of dev$ypix in the file ypix.plot1
ap> qphot dev$ypix 5. 10. 5. 2.,4.,6.0
... type ? to see the help screen
... move image cursor to objects of interest and tap space bar
... a 1 line summary will be printed on the standard output
for each object measured
... type q to quit and q again to confirm the quit
... full output will be written to ypix.mag.2
ap> set stdimcur = <default>
... reset stdimcur to its previous value
3. Setup and run QPHOT interactively on a list of objects temporarily overriding the fwhmpsf, sigma, cbox, annulus, dannulus, and apertures parameters determined in examples 1 or 2.
ap> daofind dev$ypix fwhmpsf=2.6 sigma=25.0 verify-
... make a coordinate list
... the output will appear in the text file ypix.coo.1
ap> qphot dev$ypix 7.0 12.0 5.0 "3.0,5.0" coords=ypix.coo.1
... type ? for optional help
... move the graphics cursor to the stars and tap space bar
or
... select stars from the input coordinate list with m / :m #
and measure with spbar
... measure stars selected from the input coordinate list
with n / n #
... a one line summary of results will appear on the standard output
for each star measured
... type q to quit and q again to confirm the quit
... the output will appear in ypix.mag.3 ...
4. Display and measure some stars in an image section and write the output coordinates in the coordinate system of the parent image.
ap> display dev$ypix[150:450,150:450] 1
... display the image section
ap> qphot dev$ypix[150:450,150:450] 7.0 12.0 5.0 "3.0,5.0" wcsout=tv
... move cursor to stars and type spbar
... type q to quit and q again to confirm quit
... output will appear in ypix.mag.4
ap> pdump ypix.mag.4 xc,yc yes | tvmark 1 STDIN col=204
5. Run QPHOT in batch mode using the coordinate file and the previously saved parameters.
ap> qphot dev$ypix 7. 12.0 5.0 "3.0,5.0" coords=ypix.coo.1 inter-
... output will appear in ypix.mag.5 ...
6. Repeat example 5 but assume that the input coordinate are ra and dec in degrees and degrees and submit the task to to the background.
ap> display dev$ypix
ap> rimcursor wcs=world > radec.coo
... move to selected stars and type any key
... type ^Z to quit
ap> qphot dev$ypix 7.0 12.0 5.0 "3.0,5.0" coords=radec.coo \
wcsin=world inter- &
... output will appear in ypix.ctr.6
ap> pdump ypix.mag.6 xc,yc yes | tvmark 1 STDIN col=204
... mark the stars on the display
7. Run QPHOT interactively without using the image display.
ap> show stdimcur
... record the default value of stdimcur
ap> set stdimcur = text
... set the image cursor to the standard input
ap> qphot dev$ypix 7.0 12.0 5.0 "3.0,5.0" coords=ypix.coo.1
... type ? for optional help
... type :m 3 to set the initial coordinates to those of the
third star in the list
... type "442 409 101 i" to enter the interactive setup menu
... enter the maximum radius in pixels for the radial profile or
accept the default with a CR
... type v to enter the default menu
... reset cbox, annulus, dannulus, and apertures using the graphics
cursor and the stellar radial profile plot
... typing <CR> after the prompt leaves the parameter at its default
value
... type q to quit the setup menu
... type r to rewind the coordinate list
... type l to measure all the stars in the coordinate list
... a one line summary of the answers will appear on the standard
output for each star measured
... type q to quit followed by q to confirm the quit
... full output will appear in the text file ypix.mag.7
ap> set stdimcur = <default>
... reset the value of stdimcur
8. Use a image cursor command file to drive the qphot task. The cursor command file shown below computes the centers, sky values, and magnitudes for 3 stars and quits the task.
ap> type cmdfile
442 410 101 \040
349 188 101 \040
225 131 101 \040
q
ap> qphot dev$ypix 7.0 12.0 5.0 "3.0,5.0" icommands=cmdfile
... full output will appear in ypix.mag.8
It is the responsibility of the user to make sure that the image displayed in the image display is the same as that specified by the image parameter.
Commands which draw to the image display are disabled by default. To enable graphics overlay on the image display, set the display parameter to "imdr", "imdg", "imdb", or "imdy" to get red, green, blue or yellow overlays. It may be necessary to run gflush and to redisplay the image to get the overlays position correctly.