From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001
From: Joseph Hunkeler <jhunkeler@gmail.com>
Date: Wed, 8 Jul 2015 20:46:52 -0400
Subject: Initial commit

---
 noao/digiphot/daophot/doc/daopars.hlp | 331 ++++++++++++++++++++++++++++++++++
 1 file changed, 331 insertions(+)
 create mode 100644 noao/digiphot/daophot/doc/daopars.hlp

(limited to 'noao/digiphot/daophot/doc/daopars.hlp')

diff --git a/noao/digiphot/daophot/doc/daopars.hlp b/noao/digiphot/daophot/doc/daopars.hlp
new file mode 100644
index 00000000..80f340b6
--- /dev/null
+++ b/noao/digiphot/daophot/doc/daopars.hlp
@@ -0,0 +1,331 @@
+.help daopars May00 noao.digiphot.daophot
+.ih
+NAME
+daopars -- edit the daophot fitting parameters
+.ih
+USAGE
+daopars
+.ih
+PARAMETERS
+.ls function = "gauss"
+The functional form of the analytic component of the PSF model computed by the
+DAOPHOT PSF task. The better this function matches the true PSF, especially in
+the cores of the stars, the smaller the interpolation errors will be. The
+choices are the following.
+
+.ls gauss
+An elliptical Gaussian function aligned along the x and y axes of the
+input image.
+.le
+.ls moffat15
+An elliptical Moffat function with a beta parameter of 1.5.
+.le
+.ls moffat25
+An elliptical Moffat function with a beta parameter of 2.5.
+.le
+.ls lorentz
+An elliptical Lorentzian function with beta parameter of 1.0.
+.le
+.ls penny1
+A Gaussian core with Lorentzian wings function, where the Gaussian core may be
+tilted, but the Lorentzian wings are elongated along the x or y axes.  The
+Lorentzian wings have a beta parameter of 1.0.
+.le
+.ls penny2
+A Gaussian core with Lorentzian wings function, where the Gaussian core and
+Lorentzian wings may be tilted in different directions.  The Lorentzian wings
+have a beta parameter of 1.0.
+.le
+.ls auto
+The PSF task computes the analytic PSF model for each of the six analytic model
+PSFs in turn and selects the one that produces the smallest standard deviation
+for the model fit.
+.le
+.ls func1,func2,...
+The PSF task computes the analytic PSF model for each of a subset of the six
+defined functions in turn, and selects the one that produces the smallest
+standard deviation for the model fit.
+.le
+
+In general "gauss" is the best and most efficient choice for a well-sampled
+ground-based image, "lorentz" is best for old ST images, and "moffat15" or
+"moffat25" are best for under-sampled ground-based images. 
+.le
+.ls varorder = 0
+The order of variability of the PSF model computed by the DAOPHOT PSF task.
+Varorder sets the number of look-up tables containing the deviations of the
+true PSF from the analytic model PSF that are computed by the model.
+.ls "-1"    
+Only the analytic function specified by \fIfunction\fR is used to compute
+the PSF model. The PSF model is constant over the image.
+.le
+.ls "0"   
+The analytic function and one look-up table are used to compute the
+PSF model. The  PSF model is constant over the image.
+.le
+.ls "1"    
+The analytic function and three look-up tables are used to compute the PSF
+model. The PSF model is linearly variable over the image, with terms
+proportional to 1, x and y.
+.le
+.ls "2"    
+The analytic function and six look-up tables are used to compute the
+PSF model. The PSF model is quadratically variable over the image, with terms
+proportional to 1, x, y, x**2, xy, y**2.
+.le
+.le
+.ls nclean = 0
+The number of additional iterations the PSF task performs to compute the PSF
+look-up tables. If \fInclean\fR is > 0, stars which contribute deviant
+residuals to the PSF look-up tables in the first iteration, will be
+down-weighted in succeeding iterations.
+.le
+.ls saturated = no
+Use saturated stars to improve the signal-to-noise in the wings of the PSF
+model computed by the PSF task? This parameter should only be set to
+"yes" where there are too few high signal-to-noise unsaturated stars
+in the image to compute a reasonable model for the stellar profile wings.
+.le
+.ls matchrad = 3.0 (scale units)
+The tolerance in scale units for matching the stellar x and y centroids in the
+input photometry file with the image cursor position. Matchrad is currently
+used by the PSTSELECT and PSF tasks to match stars shown on the image display
+with stars in the photometry list.
+.le
+.ls psfrad = 11.0 (scale units)
+The radius of the circle in scale units within which the PSF model is defined.
+Psfrad should be a pixel or two larger than the radius at which the intensity
+of the brightest star of interest fades into the noise. Psfrad can never be
+set larger than the size of the PSF model but may set smaller in tasks
+like GROUP, ALLSTAR, SUBSTAR, and ADDSTAR.
+.le
+.ls fitrad = 3.0 (scale units)
+The fitting radius in scale units. Only pixels within the fitting radius of
+the center of a star will contribute to the fits computed by the PEAK, NSTAR
+and ALLSTAR tasks. For most images the fitting radius should be approximately
+equal to the FWHM of the PSF. Under severely crowded conditions a somewhat
+smaller value may be used in order to improve the fit. If the PSF is variable,
+the FWHM is very small, or sky fitting is enabled in PEAK and NSTAR on the
+other hand, it may be necessary to increase the fitting radius to achieve a
+good fit.
+.le
+.ls recenter = yes (peak, nstar, and allstar)
+Compute new positions as well as magnitudes for all the stars in the input
+photometry list?
+.le
+.ls fitsky = no (peak, nstar, and allstar)
+Compute new sky values for the stars in the input list (peak, nstar, allstar).
+If fitsky = "no", the PEAK, NSTAR, and ALLSTAR tasks compute a group sky value
+by averaging the sky values of the stars in the group.  If fitsky = "yes",
+PEAK and NSTAR fit the group sky simultaneously with the positions and
+magnitudes. If fitsky = yes the ALLSTAR task computes new sky values for each
+star every third iteration by subtracting off the best current fit for the star
+and and estimating the median of the pixels in the annulus defined by
+\fIsannulus\fR and \fIwsannulus\fR. The new group sky value is the average of
+the new individual values.
+.le
+.ls groupsky = yes (nstar and allstar)
+If groupsky is "yes",  then the sky value for every pixel which contributes to
+the fit is identical and equal to the mean of the sky values of all the stars
+in the group.  If \fIgroupsky\fR is "no",  then the sky value for every pixel
+which contributes to the fit is equal to the mean of the sky values of all the
+stars in the group for which that pixel is within one fitting radius.
+.le
+.ls sannulus = 0.0 (scale units, allstar)
+The inner radius of the sky annulus used by ALLSTAR to recompute the sky 
+values.
+.le
+.ls wsannulus = 11 (scale units, allstar)
+The width of the sky annulus used by ALLSTAR to recompute the sky values.
+.le
+.ls flaterr=0.75 (percent, peak, nstar, allstar)
+The image flat-fielding error in percent used to compute the predicted
+errors of the fit.
+.le
+.ls proferr = 5.0 (percent, peak, nstar, allstar)
+The profile or interpolation fitting error in percent used to compute
+the predicted errors of the fit.
+.le
+.ls maxiter = 50 (peak, nstar, allstar)
+The maximum number of times that the PSF fitting tasks PEAK, NSTAR, and ALLSTAR
+will iterate on the PSF fit before giving up.
+.le
+.ls cliprange = 2.5, clipexp = 6.0 (peak, nstar, allstar)
+The parameters of the down-weighting scheme in the fitting code used to resist
+bad data. For values of clipexp greater than 1 a residual small compared to
+cliprange standard deviations does not have its weight significantly altered,
+one with exactly \fIcliprange\fR standard deviations is assigned half its
+normal weight, and large residuals are assigned weights which fall off as the
+standard deviation to the minus clipexp power. For normal applications users
+should leave these parameter at their default value.
+.le
+.ls critsnratio = 1.0 (group)
+The ratio of the model intensity of the brighter star computed at a distance of
+one fitting radius from the center of the fainter star, to the expected random
+error computed from the readout noise, gain and value of the PSF. The critical
+signal-to-noise ratio parameter is used to group stars. In general if a small
+value such as 0.1 divides all the stars in an image into groups less than
+\fImaxgroup\fR, then the expected random errors will determine the accuracy
+of the photometry. On the other hand if a value of critical overlap much
+greater than one is required to divide up the stars, crowding errors will
+dominate random errors. If a value of 1 is sufficient then crowding and
+random errors are roughly equivalent.
+.le
+.ls mergerad = INDEF (scale units, nstar, allstar)
+The critical separation in scale units between two objects for an object merger
+to be considered. Objects with separations > mergerad will not be merged; faint
+objects with separations <= mergerad will be considered for merging. The
+default value of mergerad is sqrt (2 *(PAR1**2 + PAR2**2)), where PAR1 and PAR2
+are the half-width at half-maximum along the major and minor axes of the psf
+model. Merging can be turned off altogether by setting mergerad to 0.0.
+.le
+.ls maxnstar = 10000 (pstselect, psf, group, allstar, substar)
+The initial star list buffer size. If there are more than maxnstar stars in the
+input photometry file buffer, DAOPHOT will resize the buffers as needed.
+The only limitation is the memory and configuration of the host computer.
+.le
+.ls maxgroup = 60 (nstar, allstar)
+The maximum numbers of stars that the multiple star fitting tasks NSTAR and
+ALLSTAR will fit simultaneously. NSTAR will not to fit groups large than
+maxgroup. ALLSTAR dynamically regroups the stars in large groups until the
+group is either maxgroup or smaller in size or becomes too dense to group,
+after which the faintest stars are rejected until the group is less than
+maxgroup ins size.
+.le
+
+.ih
+DESCRIPTION
+
+DAOPARS is a parameter set task which stores the DAOPHOT parameters
+required by all those DAOPHOT tasks which compute the PSF model, fit stars
+to the PSF model, or evaluate the PSF model.
+
+Typing DAOPARS on the terminal invokes the EPAR parameter editing task. The
+DAOPARS parameters may also be edited from within an EPAR command on task,
+for example PSF, which references them. The DAOPARS parameters may also
+be changed on the command line in the usual manner when any task which
+references them is executed.
+
+Any given set of DAOPARS parameters may stored in a text file along with
+the data being reduced by typing the :w command from within the EPAR task. If
+the user then sets the value of the \fIdaopars\fR parameter to the name of
+the file containing the stored parameter set, the stored parameters will be
+used instead of the default set in the uparm directory.
+
+.ih
+ALGORITHMS
+
+The functional forms of the analytic PSF functions are as follows. The
+A is simply an amplitude or normalization constant The Pn are parameters
+which are fit during the PSF model generation process.
+
+.nf
+	z = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2
+	gauss = A * exp (-0.5 * z)
+
+	z = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2 + x * y * p3
+	moffat15 = A / (1 + z) ** 1.5
+	moffat25 = A / (1 + z) ** 2.5
+
+	z = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2 + x * y * p3
+	lorentz = A / (1.0 + z)
+
+	z = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2
+	e = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2 + x * y * p4
+	penny1 = A * ((1 - p3) / (1.0 + z) + p3 * exp (-0.693*e))
+
+	z = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2 + p5 * x * y
+	e = x ** 2 / p1 ** 2 + y ** 2 / p2 ** 2 + x * y * p4
+	penny2 = A * ((1 - p3) / (1.0 + z) + p3 * exp (-0.693*e))
+.fi
+
+
+The predicted errors in the DAOPHOT photometry are computed per
+pixel as follows, where terms 1, 2, 3, and 4 represent the readout
+noise, the poisson noise, the flat-fielding error, and the interpolation
+error respectively. The quantities readnoise, epadu, I, M, p1, and p2
+are the readout noise in electrons, the gain in electrons per ADU,
+the pixel intensity in ADU, the PSF model intensity in ADU, the FWHM
+in x and the FWHM in y, both in pixels.
+
+.nf
+	error = sqrt (term1 + term2 + term3 + term4)  (ADU)
+	term1 = (readnoise / epadu) ** 2
+	term2 = I / epadu 
+	term3 = (.01 * flaterr * I) ** 2
+	term4 = (.01 * proferr * M / p1 / p2) ** 2
+.fi
+
+The radial weighting function employed by all the PSF fitting tasks is
+the following, where dx and dy are the distance of the pixel from the
+centroid of the star being fit.
+
+.nf
+	wtr = 5.0 / (5.0 + rsq / (1.0 - rsq))
+	rsq = (dx ** 2 + dy ** 2) / fitrad ** 2
+.fi
+
+The weight assigned each pixel in the fit then becomes the following.
+
+.nf
+	wtp = wtr / error ** 2 
+.fi
+
+After a few iterations and if clipexp > 0, a clipping scheme to reject bad
+data is enabled.  The weights of the pixels are recomputed as follows.
+
+.nf
+	wt = wtp / (1.0 + (residual / error / chiold /
+	     cliprange) ** clipexp)
+.fi
+
+Pixels having a residual of cliprange sigma will have their weight reduced
+by half.
+
+.ih
+EXAMPLES
+
+1. Print the DAOPARS task parameters.
+
+.nf
+    da> lpar daopars
+.fi
+
+2. Edit the DAOPARS parameters.
+
+.nf
+    da> daopars
+.fi
+
+3. Edit the DAOPARS parameters from with the PSF task.
+
+.nf
+    da> epar psf
+
+	... edit a few psf parameters
+
+	... move to the daopars parameter and type :e
+
+	... edit the daopars parameters and type :wq
+
+	... finish editing the psf parameters and type :wq
+.fi
+
+4. Save the current DAOPARS parameter set in a text file daonite1.par.
+   This can also be done from inside a higher level task as in the
+   above example.
+
+.nf
+    da> epar daopars
+
+	... type ":w daonite1.par"  from within epar
+.fi
+
+.ih
+TIME REQUIREMENTS
+.ih
+BUGS
+.ih
+SEE ALSO
+pstselect,psf,peak,group,nstar,allstar,substar,addstar,setimpars
+.endhelp
-- 
cgit 

