.help fitpsf May00 noao.digiphot.apphot .ih NAME fitpsf -- model the point spread function with an analytic function .ih USAGE fitpsf image box .ih PARAMETERS .ls image The list of images containing the objects to be measured. .le .ls box The width of the fitting box in scale units. .le .ls coords = "" The list of text files containing initial coordinates for the objects to be centered. Objects are listed in coords one object per line with the initial coordinate values in columns one and two. The number of coordinate files must be zero, one, or equal to the number of images. If coords is "default", "dir$default", or a directory specification then an coords file name of the form dir$root.extension.version is constructed and searched for, where dir is the directory, root is the root image name, extension is "coo" and version is the next available version number for the file. .le .ls output = "default" The name of the results file or results directory. If output is "default", "dir$default", or a directory specification then an output file name of the form dir$root.extension.version is constructed, where dir is the directory, root is the root image name, extension is "psf" and version is the next available version number for the file. The number of output files must be zero, one, or equal to the number of image files. In both interactive and batch mode full output is written to output. In interactive mode an output summary is also written to the standard output. .le .ls datapars = "" The name of the file containing the data dependent parameters. The critical parameters \fIfwhmpsf\fR and \fIsigma\fR are located in datapars. If datapars is undefined then the default parameter set in uparm directory is used. .le .ls function = "radgauss" The function to be fit. The options are: .ls radgauss A 2D radial Gaussian function is fit. The parameters of the fitting function are: x and y center, sigma of the Gaussian, amplitude of the Gaussian and the local sky value. .le .ls elgauss A 2D elliptical Gaussian function is fit. The parameters of the fitting function are: x and y center, x and y sigma of the Gaussian, amplitude of the Gaussian and the local sky value. .le .ls moments The 0th, 1st and 2nd order moments are computed and used to derive estimates of the x and y center values, radius of gyration, ellipticity and position angle of the object. .le .le .ls maxiter = 50 The maximum number of iterations that the non-linear fitting routines will perform in an attempt to find a satisfactory fit. .le .ls nreject = 0 The maximum number of rejection cycles performed after the fit. The default is no rejection. .le .ls kreject = 3.0 The k-sigma rejection limit in units of sigma. .le .ls mkbox = no Draw the fitting box on the image display? .le .ls interactive = yes Run the task interactively ? .le .ls icommands = "" The image cursor or image cursor command file. .le .ls gcommands = "" The graphics cursor or graphics cursor command file. .le .ls wcsin = ")_.wcsin", wcsout = ")_.wcsout" The coordinate system of the input coordinates read from \fIcoords\fR and of the output coordinates written to \fIoutput\fR respectively. The image header coordinate system is used to transform from the input coordinate system to the "logical" pixel coordinate system used internally, and from the internal "logical" pixel coordinate system to the output coordinate system. The input coordinate system options are "logical", tv", "physical", and "world". The output coordinate system options are "logical", "tv", and "physical". The image cursor coordinate system is assumed to be the "tv" system. .ls logical Logical coordinates are pixel coordinates relative to the current image. The logical coordinate system is the coordinate system used by the image input/output routines to access the image data on disk. In the logical coordinate system the coordinates of the first pixel of a 2D image, e.g. dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] are always (1,1). .le .ls tv Tv coordinates are the pixel coordinates used by the display servers. Tv coordinates include the effects of any input image section, but do not include the effects of previous linear transformations. If the input image name does not include an image section, then tv coordinates are identical to logical coordinates. If the input image name does include a section, and the input image has not been linearly transformed or copied from a parent image, tv coordinates are identical to physical coordinates. In the tv coordinate system the coordinates of the first pixel of a 2D image, e.g. dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] are (1,1) and (200,200) respectively. .le .ls physical Physical coordinates are pixel coordinates invariant with respect to linear transformations of the physical image data. For example, if the current image was created by extracting a section of another image, the physical coordinates of an object in the current image will be equal to the physical coordinates of the same object in the parent image, although the logical coordinates will be different. In the physical coordinate system the coordinates of the first pixel of a 2D image, e.g. dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300] are (1,1) and (200,200) respectively. .le .ls world World coordinates are image coordinates in any units which are invariant with respect to linear transformations of the physical image data. For example, the ra and dec of an object will always be the same no matter how the image is linearly transformed. The units of input world coordinates must be the same as those expected by the image header wcs, e. g. degrees and degrees for celestial coordinate systems. .le The wcsin and wcsout parameters default to the values of the package parameters of the same name. The default values of the package parameters wcsin and wcsout are "logical" and "logical" respectively. .le .le .ls cache = ")_.cache" Cache the image pixels in memory. Cache may be set to the value of the apphot package parameter (the default), "yes", or "no". By default cacheing is disabled. .le .ls verify = ")_.verify" Verify the critical parameters in non-interactive mode ? Verify may be set to the apphot package parameter value (the default), "yes", or "no. .le .ls update = ")_.update" Update the critical parameters in non-interactive mode if verify is set of "yes" ? Update may be set to the apphot package parameter value (the default), "yes", or "no. .le .ls verbose = ")_.verbose" Print messages on the terminal in non-interactive mode ? Verbose may be set to the apphot package parameter value (the default), "yes", or "no. .le .ls graphics = ")_.graphics" The default graphics device. Graphics may be set to the apphot package parameter value (the default), "yes", or "no. .le .ls display = ")_.display" The default display device. Display may be set to the apphot package parameter value (the default), "yes", or "no. By default graphics overlay is disabled. Setting display to one of "imdr", "imdg", "imdb", or "imdy" enables graphics overlay with the IMD graphics kernel. Setting display to "stdgraph" enables FITPSF to work interactively from a contour plot. .le .ih DESCRIPTION FITPSF models the stellar brightness distribution of objects in the IRAF image \fIimage\fR using non-linear least squares techniques and writes the list of model parameters and associated errors to the file \fIoutput\fR. Initial coordinates for the objects are read from the image cursor or the text file \fIcoords\fR. Pixels in a subraster of width \fIbox * scale\fR are extracted and used in the fit. The coordinates read from \fIcoords\fR are assumed to be in coordinate system defined by \fIwcsin\fR. 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 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 \fIoutput\fR are in the coordinate system defined by \fIwcsout\fR. 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 pieces with coordinates in the parent image must use the "tv" or "physical" coordinate systems. If \fIcache\fR 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 FITPSF 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 FITPSF 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. FITPSF can be run either interactively or in batch mode by setting the parameter \fIinteractive\fR. In interactive mode starting x and y positions can either be read directly from the image cursor or read from the text file specified by \fIcoords\fR. In batch mode the estimated positions can be read from the text file \fIcoords\fR or the image cursor parameter \fIicommands\fR can be redirected to a text file containing a list of cursor commands. .ih CURSOR COMMANDS The currently available cursor commands are listed below. .nf Interactive Keystroke Commands ? Print help : Colon commands v Verify the critical parameters w Save the current parameters d Plot radial profile of current star i Interactively set parameters using current star f Fit current star spbar Fit current star, output results m Move to next star in coordinate list n Fit next star in coordinate list, output results l Fit remaining stars in coordinate list, output results e Print error messages r Rewind the coordinate list q Exit task Colon Commands :show [data/fit] List the parameters :m [n] Move to next [nth] star in coordinate list :n [n] Fit next [nth] star in coordinate list, output results Colon Parameter Editing Commands # Image and file name parameters :image [string] Image name :coords [string] Coordinate file name :output [string] Output file name # Data dependent parameters :scale [value] Image scale (units per pixel) :fwhmpsf [value] Scale factor (scale units) :emission [y/n] Emission feature (y), absorption (n) :sigma [value] Standard deviation of sky (counts) :datamin [value] Minimum good data value (counts) :datamax [value] Maximum good data value (counts) # Noise description 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 adu) :readnoise [value] Readnoise (electrons) # Observation 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] Exposure time (time units) :xairmass [value] Airmass value (number) :ifilter [string] Filter id string :otime [string] Time of observation (time units) # Fitting parameters :function [string] PSF model (radgauss|elgauss|moments) :box [value] Width of the fitting box (scale units) :maxiter [value] Maximum number of iterations :nreject [value] Maximum number of rejection cycles :kreject [value] Rejection limit (sigma) # Plotting and marking functions :mkbox [y/n] Mark the fitting box on the display The following command are available from within the interactive setup menu. Interactive Fitpsf Setup Menu v Mark and verify the critical fitpsf parameters (f,s,b) f Mark and verify the full-width half-maximum of the psf 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 b Mark and verify the half-width of the fitting box .fi .ih ALGORITHMS The fitting parameters are \fIfunction\fR, the functional form of the model to be fit, \fImaxiter\fR, the maximum number of iterations per fit, \fIkreject\fR, the K-sigma rejection limit and \fInreject\fR, the maximum number of rejection cycles. The currently available functions are a 2D moments analysis "moments", a 2D radial Gaussian "radgauss", and a 2D elliptical Gaussian "elgauss". The weighting of the fit is determined by the parameter \fInoise\fR in the \fIdatapars\fR file. The two options are \fIconstant\fR, in which all the weights are set to 1 and \fIpoisson\fR in which the weights are equal to the inverse of the counts divided by the image gain read from the datapars \fIgain\fR or \fIepadu\fR parameters plus the square of the readout noise determined from the datapars parameters \fIccdread\fR or \fIreadnoise\fR. If \fIfunction\fR is either "radgauss" or "ellgauss" then the datapars parameter \fIfwhmpsf\fR is used to determine the initial guess for the Gaussian sigma. The datapars parameter \fIthreshold\fR determines the intensity threshold above which the moment analysis is performed. .ih OUTPUT In interactive mode the following quantities are printed on the terminal as shown below, for the radial Gaussian, elliptical Gaussian and moments functions respectively. .nf image xcenter ycenter rsigma amplitude sky err image xcenter ycenter xsigma ysigma rot amplitude sky err image xcenter ycenter rgyrat ellip pa amplitude sky err .fi In both interactive and batch mode the full output is written to the text file \fIoutput\fR. At the beginning of each file is a header listing the 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 for the radial Gaussian, elliptical Gaussian, and moments functions respectively. .nf image xinit yinit id coords lid xcenter ycenter rsigma amplitude sky excenter eycenter ersigma eamplitude esky ier error image xinit yinit id coords lid xcenter ycenter xsigma ysigma rot amplitude sky excenter eycenter exsigma eysigma erot eamplitude esky ier\ error image xinit yinit id coords lid xcenter ycenter rgyrat ellip pa amplitude sky excenter eycenter ergyrat eellip epa eamplitude esky ier\ error .fi Image and coords are the name of the image and coordinate files respectively. Id and lid are the sequence numbers of stars in the output and coordinate files respectively and xinit and yinit are the initial positions. Xcenter and ycenter are the computed x and y positions of the object. Rsigma, xsigma and ysigma are the distance from the center of the Gaussian at which the Gaussian is equal to exp (-0.5) of its central value. Xsigma and ysigma refer to those values along the major and minor axes of the ellipse respectively. The amplitude and sky refer to the amplitude of the Gaussian function and a constant background value respectively. If function = "moments" amplitude and sky refer to the total intensity above threshold and sky is the threshold value. Rot and pa are position angles of the major axis measured counter-clockwise with respect to the x axis. Rgyrat is the radius of gyration of the object and ellip its ellipticity. Quantities prefixed by an e represent the errors in the corresponding fitted parameters. .ih ERRORS If all went well in the fitting process the error code stored in the ier field described above is 0. Non-zero values of ier flag the following error conditions. .nf 0 # No error 401 # The fitting box is off the image 402 # The fitting box is partially off the image 403 # There are too few points to fit the function 404 # The fit is singular 405 # The fit did not converge .fi .ih EXAMPLES 1. Compute the radial Gaussian function parameters for a few stars in dev$ypix using the display and the image cursor. Setup the task parameters using the interactive setup menu defined by the i key command. Use uniform weighting. .nf ap> display dev$ypix 1 fi+ ... display the image ap> fitpsf dev$ypix 11 noise=constant ... type ? to see the help screen ... move the image cursor to a star ... type i to enter the interactive setup menu ... enter maximum radius in pixels of the radial profile or type CR to accept the default value ... set the fitting box width, fwhmpsf, and sigma using the graphics cursor and the stellar radial profile plot ... typing leaves everything at the default value ... type q to quit the setup menu ... type the v key to verify the parameters ... 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 ... type q to quit and another q to confirm the quit ... the full output will appear in ypix.psf.1 .fi 2. Compute the radial Gaussian function parameters for a few stars in dev$ypix using the contour plot and the graphics cursor. Setup the task parameters using the interactive setup menu defined by the i key command. Use uniform weighting. .nf ap> show stdimcur ... save the current value of stdimcur ap> set stdimcur = stdgraph ... define the image cursor to be the graphics cursor ap> contour dev$ypix >G ypix.plot1 ... store the contour plot of dev$ypix in the file ypix.plot1 ap> fitpsf dev$ypix 11.0 noise=constant display=stdgraph ... type ? to get a short help page on the screen ... move the graphics cursor to a star ... type i to enter the interactive setup menu ... enter the maximum radius in pixels of the radial profile or type CR to accept the default value ... set the fitting box width, fwhmpsf, and sigma using the graphics cursor and the stellar radial profile plot ... typing leaves everything at the default value ... type q to quit the setup menu ... type the v key to verify critical parameters ... type the w key to save the parameters in the parameter files ... retype :.read ypix.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 ... type q to quit and q again to confirm the quit ... full output will appear in the text file ypix.psf.2 .fi 3. Setup and run FITPSF interactively on a list of objects temporarily overriding the fwhmpsf and sigma parameters determined in examples 1 or 2. Use uniform weighting. .nf 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> fitpsf dev$ypix 11.0 fwhmpsf=2.6 noise=constant 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.psf.3 ... .fi 4. Display and fit some stars in an image section and write the output coordinates in the coordinate system of the parent image. Use uniform weighting. .nf ap> display dev$ypix[150:450,150:450] 1 ... display the image section ap> fitpsf dev$ypix[150:450,150:450] 11.0 noise=constant wcsout=tv ... move cursor to stars and type spbar ... type q to quit and q again to confirm quit ... output will appear in ypix.psf.4 ap> pdump ypix.psf.4 xc,yc yes | tvmark 1 STDIN col=204 .fi 5. Run FITPSF in batch mode using the coordinate file and the previously saved parameters. Use uniform weighting. Verify the critical parameters. .nf ap> fitpsf dev$ypix 11.0 coords=ypix.coo.1 noise=constant verify+ \ inter- ... output will appear in ypix.psf.5 ... .fi 6. Repeat example 5 but assume that the input coordinate are ra and dec in degrees and degrees, turn off verification, and submit the task to to the background. Use uniform weighting. .nf ap> display dev$ypix 1 ap> rimcursor wcs=world > radec.coo ... move to selected stars and type any key ... type ^Z to quit ap> fitpsf dev$ypix 11.0 coords=radec.coo noise=constant \ wcsin=world verify- inter- & ... output will appear in ypix.psf.6 ap> pdump ypix.psf.6 xc,yc yes | tvmark 1 STDIN col=204 ... mark the stars on the display .fi 7. Run FITPSF interactively without using the image display. .nf ap> show stdimcur ... record the default value of stdimcur ap> set stdimcur = text ... set the image cursor to the standard input ap> fitpsf dev$ypix 11.0 coords=ypix.coo.1 noise=constant ... type ? for optional help ... type :m 3 to set the initial coordinates to those of the third star in the list ... type 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 ... set the fwhmpsf, sigma, and fitting box size using the graphics cursor and the stellar radial profile plot ... typing 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.psf.7 ap> set stdimcur = ... reset the value of stdimcur .fi 8. Use an image cursor command file to drive the FITPSF task. The cursor command file shown below sets the fwhmpsf, sigma, and noise, computes the model fit parameter values for 3 stars, updates the parameter files, and quits the task. .nf ap> type cmdfile : fwhmpsf 2.6 : sigma 5.0 : noise constant 442 410 101 \040 349 188 101 \040 225 131 101 \040 w q ap> fitpsf dev$ypix 11.0 icommands=cmdfile verify- ... full output will appear in ypix.psf.8 .fi .ih BUGS In interactive mode the user should not change the type function to be fit after the first record is written to the output file. In this case the file header and record structure will not match. It is currently the responsibility of the user to make sure that the image displayed in the frame 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 and set the mkbox switch to"yes". It may be necessary to run gflush and to redisplay the image to get the overlays position correctly. .ih SEE ALSO datapars, radprof .endhelp