IRAF help page for package noao.digiphot.apphot, program polyphot

• image
• coords =
• polygons =
• output = default
• datapars =
• centerpars =
• fitskypars =
• polypars =
• interactive = yes
• verify = yes
• update = yes
• verbose = no
• graphics = stdgraph
• display = stdimage
• icommands =
• gcommands =

polyphot image

image

coords =

polygons =

output = default

datapars =

centerpars =

fitskypars =

polypars =

interactive = yes

verify = yes

update = yes

verbose = no

graphics = stdgraph

display = stdimage

icommands =

gcommands =

POLYPHOT computes the magnitude of an object in the IRAF image image inside a polygonal aperture whose vertices are listed in the text file polygons or are marked on the display interactively with the image cursor. The polygon can be shifted by specifying the center coordinates of the polygons in polygons in the text file coords or by using the image cursor if the polygon was drawn interactively.

POLYPHOT can be run either interactively or in batch mode by setting the parameter interactive. In interactive mode starting x and y positions can either be read directly from the image cursor or read from the text files polygons and coords.

The following polyphot commands are currently available.

	Interactive Keystroke Commands
?	Print help
:	Colon commands
v	Verify the critical parameters
w	Store the current parameters
d	Plot radial profile of current object
i	Define current polygon, graphically set parameters using current object
g	Define current polygon 
c	Fit center for current object
t	Fit sky around cursor
a       Average sky values fit around several cursor positions
s	Fit sky around current object
h	Do photometry for current polygon
j	Do photometry for current polygon, output results
p	Do photometry for current object using current sky
o	Do photometry for current object using current sky, output results
f	Do photometry for current object
spbar	Do photometry for current object, output results
m	Move to next object in coordinate list
n	Do photometry for next object in coordinate list, output results
l	Do photometry for remaining objects in list, output results
r	Rewind the polygon list
e	Print error messages
q	Exit task
	Colon Commands
:show	[data/center/sky/phot]	List the parameters
:m [n]	Move to next [nth] object in coordinate list
:n [n]	Do photometry for next [nth] object in coordinate list, output results
	Colon Parameter Editing Commands
# Image and file name parameters
:image		[string]	Image name
:polygon	[string]	Polygon file
:coords		[string]	Coordinate file
:output		[string]	Results file
# Data dependent parameters
:scale		[value]		Image scale (units per pixel)
:fwhmpsf	[value]		Full-width half-maximum of PSF (scale units)
:emission	[y/n]		Emission feature (y), absorption (n)
:sigma		[value]		Standard deviation of sky (counts)
:datamin	[value]		Minimum good pixel value (counts)
:datamax	[value]		Maximum good pixel value (counts)
# Noise parameters
:noise		[string]	Noise model (constant|poisson)
:gain		[string]	Gain image header keyword
:ccdread	[string]	Readout noise image header keyword
:epadu		[value]		Gain (electrons per count)
:epadu		[value]		Readout noise (electrons)
# Observing parameters
: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
:itime		[value]		Integration time (time units)
:xairmass	[value]		Airmass value (number)
:ifilter	[string]	Filter id string
:otime		[string]	Time of observation (time units)
# Centering algorithm parameters
:calgorithm	[string]	Centering algorithm
:cbox		[value]		Width of centering box (scale units)
:cthreshold	[value]		Centering intensity threshold (sigma)
:cmaxiter	[value]		Maximum number of iterations
:maxshift	[value]		Maximum center shift (scale units)
:minsnratio	[value]		Minimum S/N ratio for centering
:clean		[y/n]		Clean subraster before centering
:rclean		[value]		Cleaning radius (scale units)
:rclip		[value]		Clipping radius (scale units)
:kclean		[value]		Clean K-sigma rejection limit (sigma)
# Sky fitting algorithm parameters
:salgorithm	[string]	Sky fitting algorithm 
:skyvalue	[value]		User supplied sky value (counts)
:annulus	[value]		Inner radius of sky annulus (scale units)
:dannulus	[value]		Width of sky annulus (scale units)
:khist		[value]		Sky histogram extent (+/- sigma)
:binsize	[value]		Resolution of sky histogram (sigma)
:sloclip	[value]		Low-side clipping factor in percent
:shiclip	[value]		High-side clipping factor in percent
:smooth		[y/n]		Lucy smooth the sky histogram
:smaxiter	[value]		Maximum number of iterations
:snreject	[value]		Maximum number of rejection cycles
:sloreject	[value]		Low-side pixel rejection limits (sky sigma)
:shireject	[value]		High-side pixel rejection limits (sky sigma)
:rgrow		[value]		Region growing radius (scale units)
# Photometry parameters
:zmag		[value]		Zero point of magnitude scale
# Plotting and marking parameters
:mkcenter	[y/n]		Mark computed centers on the display
:mksky		[y/n]		Mark the sky annuli on the display
:mkpolygon	[y/n]		Mark the polygon on the display
The following commands are available from inside the interactive setup menu.
                    Interactive Photometry Setup Menu
	v	Mark and verify the critical parameters (f,c,s,a,d)
	f	Mark and verify the psf full-width half-maximum
	s	Mark and verify the standard deviation of the background
	l	Mark and verify the minimum good data value
	u	Mark and verify the maximum good data value
	c	Mark and verify the centering box width
	n	Mark and verify the cleaning radius
	p	Mark and verify the clipping radius
	a	Mark and verify the inner radius of the sky annulus
	d	Mark and verify the width of the sky annulus
	g	Mark and verify the region growing radius

A brief description of the data dependent parameters, the centering algorithms and the sky fitting algorithms can be found in the online manual pages for the DATAPARS, CENTERPARS, and FITSKYPARS tasks. A full description of the algorithms can be found in the document Specifications for the Apphot Package.

POLYPHOT computes the intersection of each image line with the line segments composing the polygon in order to determine the extent of the polygon . A one dimensional summation including a fractional approximation for the end pixels is performed over those regions of the image line which intersect the polygon. All the 1D summations are summed to give the total integral. The vertices of the polygon must be specified in order either clockwise or counterclockwise.

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 in the centering algorithm, the sky fitting algorithm or the photometry algorithm. Mag are the magnitudes in the polygonal aperture and xcenter, ycenter and msky are the x and y centers and the sky value respectively.

    image  xcenter  ycenter  msky  mag  merr 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 error
	   msky  stdev  sskew  nsky  nsrej  sier  serror
	   itime  xairmass  ifilter  otime
	   sum  area  mag  merr  pier  perr
	   polygons  pid  oldxmean  oldymean  xmean  ymean  maxrad  nver
	   xvertex  yvertex

Image and coords are the name of the image and coordinate file respectively. Id and lid are the sequence numbers of objects in the output and coordinate files respectively. Cier and cerror are the centering error code and accompanying error message respectively. 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 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 from the fit respectively.

Itime is the exposure time, xairmass is self-evident, ifilter is an id string identifying the filter used during the observation, and otime is a string specifying the time of the observation in whatever units the user has chosen.

Sum, and area are the total number of counts including sky in the polygonal aperture and the area of the aperture in square pixels. Mag and merr are the magnitude and error in the magnitude in the aperture after subtracting the sky background (see below).

        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.

Polygons and pid are the name of the polygons file and the polygon id respectively. Oldxmean, oldymean, xmean and ymean are the original and current average coordinates of the current polygon. Oldxmean and oldymean are the values in the polygons file or the values which correspond to the polygon drawn on the display. Xinit and yinit define the position to which the polygonal aperture was shifted. Xmean and ymean are generally identical to xcenter and ycenter and describe the position of the centered polygonal aperture. Maxrad is the maximum distance of a polygon vertex from the average of the vertices. Nver, xvertex and yvertex are the number of vertices and the coordinates of the vertices of the polygonal aperture.

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 maxshift
	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 conditins.

	0       # No error
	801	# The polygon is undefined
	802     # The polygon is partially off the image
	803     # The polygon is off the image
	804     # The sky value is undefined
	805     # There is bad data in the aperture

1. Compute the magnitudes inside a polygonal aperture for a few stars in N4147 using the display and the image cursor. Setup the task parameters using the interactive setup menu defined by the i key command.

	ap> set stdimcur = stdimage
	... define the image cursor
	ap> display n4147 1 fi+
	... display the image
	ap> polyphot n4147 
	... type ? to print a help page
	... move image cursor to a star
	... type i to enter the interactive setup menu
	... use the image cursor to mark the vertices of the polygonal
       	    aperture as directed
	... mark each vertex only once, POLYPHOT will close the polygon
	    for you
	... enter maximum radius in pixels of the radial profile
	... set the fwhmpsf, centering radius, inner and outer sky annuli,
	    and sigma using the graphics cursor and the stellar radial
	    profile plot, verifying each value
	... typing  leaves everything at the default value
	... type the v key to verify the parameters one more time
	... type the w key to save the parameters in the parameter files
	... move the image cursor to the stars of interest and tap
	    the space bar
	... a one line summary of the fitted parameters will appear on the
	    standard output for each star measured
	... the output will appear in n4147.ply.1

2. Compute the magnitudes inside a polygonal aperture for a few stars in M92 using a contour plot and the graphics cursor. Setup the task parameters using the interactive setup menu defined by the i key command.

	ap> set stdimcur = stdgraph
	... define the image cursor to be the graphics cursor
	ap> contour m92 >G m92.plot1
	... store the contour plot of m92 in the file m92.plot
	ap> polyphot m92 display=stdgraph mkpoly+
	... type ? to print a help page
	... type :.read m92.plot1 to load the contour plot on the screen
	... move graphics cursor to a star
	... type i to enter the interactive setup menu
	... use the graphics cursor as directed  to draw the polygonal
	    aperture
	... mark each vertex only once, POLYPHOT will close the polygon
	    for you
	... enter maximum radius in pixels of the radial profile
	... set the fwhmpsf, centering radius, inner and outer sky annuli,
	    and sigma using the graphics cursor and the stellar radial
	    profile plot, verifying each entry
	... typing  leaves everything at the default value
	... type the v key one more time to verify the parameters
	... type the w key to save the parameters in the parameter files
	... retype :.read m92.plot1 to reload the contour plot
	... move the graphics cursor to the stars of interest and tap
	    the space bar
	... a one line summary of the fitted parameters will appear on the
	    standard output for each star measured and the polygons will
	    be drawn on the display
	... full output will appear in the text file m92.ply.1 

3. Setup and run POLYPHOT interactively on a list of objects, using a contour plot as the image display and the parameters defined and saved in example 1.

	ap> set stdimcur = stdgraph
	... define the image cursor to be the graphics cursor
	ap> contour m92
	... adjust plot parameters until the contour plot is satisfactory
	ap> =gcur
	... enter cursor mode
	... type :.write m92.plot2 to save the plot in a metacode file
	... type any key to quit cursor mode
	ap> polymark m92 
	... type g to draw a polygon on the display and follow the
	    instructions 
	... mark each vertex only once, POLYPHOT will close the
	    polygon for you
	... move the graphics cursor to the stars of interest and tap
	    the space bar
	... the coordinates and the polygonal aperture  will be written
	    to the text files m92.coo.1 and m92.ver.1 respectively
	... type q to quit
	ap> polyphot m92 coords=m92.coo.1 poly=m92.ver.1 display=stdgraph 
	    mkpoly+
	... type ? to print a help page
	... type :.read m92.plot2 to read in the contour plot
	... type :n 1 to measure the first object in the list
	... if everything looks okay type l to measure the rest of the stars 
	... a one line summary of results will appear on the standard output
	    for each star measured and the aperture will be plotted on
	    the contour plot
	... the output will appear in m92.ply.2 ...

	ap> polyphot m92 coords=m92.coo.1 poly=m92.ver.1 inter- verify+
	... output will appear in m92.ply.3

	ap> polyphot m92 coords=m92.coo.1 poly=m92.ver.1 inter- verify- &
	... output will appear in m92.ply.4