diff options
Diffstat (limited to 'noao/obsutil/src/doc')
| -rw-r--r-- | noao/obsutil/src/doc/bitcount.hlp | 80 | ||||
| -rw-r--r-- | noao/obsutil/src/doc/ccdtime.hlp | 364 | ||||
| -rw-r--r-- | noao/obsutil/src/doc/cgiparse.hlp | 166 | ||||
| -rw-r--r-- | noao/obsutil/src/doc/findgain.hlp | 168 | ||||
| -rw-r--r-- | noao/obsutil/src/doc/kpnofocus.hlp | 214 | ||||
| -rw-r--r-- | noao/obsutil/src/doc/pairmass.hlp | 132 | ||||
| -rw-r--r-- | noao/obsutil/src/doc/psfmeasure.hlp | 633 | ||||
| -rw-r--r-- | noao/obsutil/src/doc/shutcor.hlp | 93 | ||||
| -rw-r--r-- | noao/obsutil/src/doc/specfocus.hlp | 375 | ||||
| -rw-r--r-- | noao/obsutil/src/doc/sptime.hlp | 1218 | ||||
| -rw-r--r-- | noao/obsutil/src/doc/starfocus.hlp | 820 |
11 files changed, 4263 insertions, 0 deletions
diff --git a/noao/obsutil/src/doc/bitcount.hlp b/noao/obsutil/src/doc/bitcount.hlp new file mode 100644 index 00000000..22744f83 --- /dev/null +++ b/noao/obsutil/src/doc/bitcount.hlp @@ -0,0 +1,80 @@ +.help bitcount Mar93 noao.obsutil +.ih +NAME +bitcount - accumulate the bit statistics for a list of images +.ih +USAGE +bitcount images +.ih +PARAMETERS +.ls images +A list of image names whose bit statistics will be counted. The +statistics can either be reported for each individual image (the +default) or as a grand total over all the images. +.le +.ls grandtotal = no +If \fIgrandtotal\fR = yes, accumulate a grand total over all the +images. If \fIgrandtotal\fR = no (the default), report the statistics +individually for each image in turn. +.le +.ls leftzeroes = yes +If \fIleftzeroes\fR = yes, leftmost zeroes are counted into the +statistics (the default). If \fIleftzeroes\fR = no, leftmost zeroes +(those past the most significant digit for each individual pixel) +are omitted from the statistics. +.le +.ls verbose = yes +If \fIverbose\fR = no, only the raw bit counts will be reported. +.le +.ih +DESCRIPTION +\fIBitcount\fR will report the absolute and relative proportions +of zeroes and ones populating each bit plane of a list of images. +This is useful for diagnosing problems with a CCD's A/D converter, +especially when an input image is supplied that contains a linear +ramp in exposure across the range of the A/D. + +The statistics for the list of images can be accumulated either +individually for each image, or as a grand total over all of the +images depending on the value of the \fIgrandtotal\fR parameter. +A single linear exposure ramp can be mimiced by a grand total +over a list of progressively more exposed images. Care should +be taken to arrange that the exposures sample all parts of the +A/D's range. + +The \fIleftzeroes\fR parameter is used to correct a problem seen +with the ctio.bitstat task. Bitstat under-reports zeroes for the +more significant bits since only pixels with values greater than +the bit being currently counted participate in that count. The +severity and precise nature of this problem depends on the exposure +level of a particular test image. \fILeftzeroes\fR may be set to +"no" if there is some reason to restore this behavior. + +The \fIverbose\fR parameter may be set to "no" in order to pass +the raw bit counts on to some other task. +.ih +EXAMPLES +To report the bit statistics for a test exposure ramp: + +.nf + nl> bitcount testramp +.fi + +To accumulate a grand total over a list of images: + +.nf + nl> bitcount a001*.imh grandtotal+ +.fi +.ih +BUGS +A warning will be issued when accumulating a grand total over a list +of images whose datatypes vary. In this case, the totals for each bit +will be correct - to the extent that some images may not populate some +bits - but the datatype of the final image in the list will control the +range of bitplanes included in the output report. The interpretation +of the most significant bit as a sign bit will also depend on the +datatype of this final image. +.ih +SEE ALSO +imstatistics, ctio.bitstat +.endhelp diff --git a/noao/obsutil/src/doc/ccdtime.hlp b/noao/obsutil/src/doc/ccdtime.hlp new file mode 100644 index 00000000..0dee4ed1 --- /dev/null +++ b/noao/obsutil/src/doc/ccdtime.hlp @@ -0,0 +1,364 @@ +.help ccdtime Nov01 noao.obsutil +.ih +NAME +ccdtime -- compute time, magnitude, and signal-to-noise for CCDs +.ih +USAGE +ccdtime +.ih +PARAMETERS +.ls time = INDEF +Time in seconds for output of magnitude at the specified signal-to-noise and +signal-to-noise at the specified magnitude. This time applies to all +filters. If specified as INDEF then no output at fixed exposure time will +be produced. If the value is not greater than zero or less than 100000 +an error is reported. +.le +.ls magnitude = 20. +Magnitude for output of time at the specified signal-to-noise and +signal-to-noise at the specified time. This magnitude applies to all +filters. If specified as INDEF then no output at fixed magnitude will +be produced. If the absolute value of the magnitude is greater than 40 +an error will be reported. +.le +.ls snr = 20. +Signal-to-noise ratio for output of time at the specified magnitude and +magnitude at the specified time. This signal-to-noise ratio applies to all +filters. If specified as INDEF then no output at fixed signal-to-noise +ratio will be produced. If the value is not greater than zero or less than +100000 an error is reported. +.le + +.ls database = "ccdtime$kpno.dat" +Database file for telescope, filter, and detector information. The format +of this file is described elsewhere. This file is typically a standard +file from the logical directory "ccdtime$" or a personal copy in a +user's directory. +.le +.ls telescope = "?" +Telescope entry from the database. If "?" a list of telescopes in the +database is produced. The name must match the entry name in the database +but ignoring case. If the same telescope has multiple focal ratios then +there must be multiple entries in the database. +.le +.ls detector = "" +Detector entry from the database. If "?" a list of detectors in the +database is produced. The name must match the entry name in the database +but ignoring case. +.le +.ls sum = 1 +CCD on-chip summing or binning factor. +.le +.ls seeing = 1.5 +Expected seeing (FWHM) in arc seconds. The number of pixels used for computing +the total star counts and the signal-to-noise is given by 1.4 times the square +of the seeing converted to pixels and rounded up. +.le +.ls airmass = 1.2 +Airmass for observation. +.le +.ls phase = 0. +Moon phase in days (0-28) for the estimation of sky brightness. A +phase of zero is new moon or dark sky conditions and a phase of 14 +is full moon. +.le + +.ls f1 = "U", f2 = "B", f3 = "V", f4 = "R", f5 = "I" +Filters for which to compute the CCD information. If given as "?" +a list of filters in the database is produced. If the name (ignoring +case) is not found then it is ignored. A null name, that is "", is used +to eliminate listing of a filter. If more than five filters is desired +each of the parameters may be a comma delimited list of desired filters. +Note that whitespace is preserved so "U, V" will expand to "U" and " V" +and so will not match "V" in the database. Use "U,V" instead. +.le +.ih +DESCRIPTION +A telescope, CCD detector, and list of filters is selected from a database +to define the expected photon/electron count rates. These rates along with +a specified seeing and airmass are used to estimate the signal-to-noise +ratio (SNR) for a stellar observation in each filter. The output provides +three results per filter; the exposure time to achieve a desired SNR for a +given magnitude, the magnitude to achieve a desired SNR in a given time, and +the SNR at a specified magnitude and exposure time. With each of these, +the number of star photons (or CCD electrons) in an area 1.4 times the +square of the seeing, the number of sky photons per pixel, and the RMS noise +contributions from photon noise in the star, the sky, and the detector +noise from dark current and read out noise are given. Note that least two +of the time, magnitude, and signal-to-noise ratio must be specified but if +one is INDEF then output with that quantity fixed will be skipped or, in +other words, only the output where the quantity is computed is produced. + +The calibration information needed to define the count rates are +taken from a database file. This file may be standard ones given in +the logical directory "ccdtime$" or the user may create their own. +The database contains entries organized by telescope name (which may +include a focal ratio if there are multiple ones), detector name, +and filter name. One of the standard files may be used as a template. + +The file is actually in free format with whitespace and comments ignored. +However, following the template formatting makes it easy to see the logical +structure. All lines, except the "end" line which separates the different +catagories of entries, consist of a keyword an equal sign, and a value +separated by whitespace. An entry begins with one of the keywords +"telescope", "detector", or "filter" and ends with the beginning of +a new entry or the "end" separator. + +A keyword is one of the words shown in the example below. These keywords +can also be indexed by the name of a telescope, filter, and/or detector +entry. This allows having different transmissions in different filters +due to correctors, different scales for different detectors which may +have fore-optics, etc. + +Specifically a keyword in the telescope section may have arguments +from the filter or detector entries, a keyword in the filter section may +have arguments from the telescope and detector entries, and a keyword +in the detector section may have arguments from the telescope and filter +entries. The formats are keyword, keyword(arg), and keyword(arg,arg). +The arg fields must match an entry name exactly (without the quotes) +and there can be no whitespace between the keyword and (, between ( +and the argument, between the arguments and the comma, and between the +last argument and the closing ). The software will first look for +keywords with both arguments in either order, then for keywords with +one argument, and then for keywords with no arguments. + +Below is an example of each type of entry: + +.nf + telescope = "0.9m" + aperture = 0.91 + scale = 30.2 + transmission = 1.0 + transmission(U) = 0.8 + transmission(U,T1KA) = 0.7 + + filter = "U" + mag = 20 + star = 18.0 + extinction = 0.2 + sky0 = 22.0 + sky1 = -0.2666 + sky2 = -.00760 + + detector = "T1KA" + rdnoise = 3.5 + dark = 0.001 + pixsize = 24 + U = 0.36 + B = 0.61 + V = 0.71 + R = 0.78 + I = 0.60 +.fi + +In the example, a transmission of 0.7 will be used if the filter is U +and the detector is T1KA, a value of 0.8 if the filter is U and the +detector is not T1KA, and a value of 1 for all other cases. + +The telescope entry contains the aperture diameter in meters, the +scale in arcsec/mm, and a transmission factor. The transmission factor is +mostly a fudge factor but may be useful if a telescope has various +configurations with additional mirrors and optics. + +The filter entry contains a fiducial magnitude and the total photon count +rate for a star of that magnitude. The units are photons per second +per square meter of aperture. An effective extinction in magnitudes/airmass is +given here. The sky is defined by a quadratic +function of lunar phase in days: + +.nf + if (phase < 14) + sky = sky0 + sky1 * phase + sky2 * phase**2 + else + sky = sky0 + sky1 * (14 - phase) + sky2 * (14 - phase)**2 +.fi + +One may set the higher order terms to zero if the moon contribution +is to be ignored. The units are magnitudes per square arc second. + +The detector entry contains the read out noise in electrons, the +dark current rate in electrons per second, the pixel size in +microns, and the detective quantum efficiency (DQE); the fraction of +detected photons converted to electrons. Note that the actual +values used are the DQE times the rates given by the filter entries. +Thus, one may set the DQE values to 1 and adjust the filter values +or set the star count rates to 1 in the filter and set the actual +count rates in the DQE values. + +The computed quantities are formally given as follows. The +star count rates for the specified telescope/detector/filter are: + +.nf + r(star) = star * aperture**2 * transmission * + 10**(0.4*(1-airmass)*extinction) * dqe +.fi + +where the "star", "aperture", "transmission", "extinction", are those +in the database and the "dqe" is the appropriate filter value. The sky +rate per pixel is: + +.nf + r(sky) = r(star) * 10 ** (0.4 * (mag - sky)) * pixel**2 + pixel = pixsize * scale * sum +.fi + +where mag is the fiducial magnitude, sky is the value computed using +the quadratic formula for the specified moon phase and the database +coefficients, the "pixel" size is computed using the CCD pixel size and +the telescope scale from the database, and sum is the +specified CCD binning factor. + +The number of pixels per star is computed from the seeing as: + +.nf + npix = 1.4 * (seeing / pixel) ** 2 +.fi + +where the number is rounded up to the next integer and a minimum of 9 +pixels is enforced. This number is a compromise between a large aperture +for high SNR stars and a smaller aperture for fainter stars. + +The number of star photons/electrons per star of magnitude m, +the number of sky photons per pixel, and the number of dark current +electrons, all in exposure time t, are given by: + +.nf + nstar = r(star) * 10 ** (0.4 * (mag - m)) * t + nsky = r(sky) * t + ndark = dark * t +.fi + +where dark is taken from the detector database entry. + +Finally the noise contributions, total noise, and signal-to-noise are +given by: + +.nf + noise star = nstar ** 1/2 + noise sky = (npix * nsky) ** 1/2 + noise ccd = (npix * (ndark + rdnoise**2)) ** 1/2 + noise total = (nstar+npix*(nsky+ndark+rdnoise**2)) ** 1/2 + SNR = nstar / noise total +.fi +.ih +EXAMPLES +1. To get a list of the telescopes, filters, and detectors in a database: + +.nf + cl> ccdtime telescope=? detector=? f1=? + Entries for telescope in database ccdtime$kpno.dat: + 0.9m + ... + 4m + Entries for detector in database ccdtime$kpno.dat: + T1KA + T2KA + T2KB + TI2 + TI3 + T5HA + S2KA + Entries for filter in database ccdtime$kpno.dat: + U + B + V + R + I +.fi + +2. The following is for the default magnitude and SNR and with +a 1 second exposure time specified. The output has some +whitespace removed to fit on this page. + +.nf + cl> ccdtime time=1 + Telescope: 0.9m + Detector: t1ka + Database: ccdtime$kpno.dat Telescope: 0.9m Detector: t1ka + Sum: 1 Arcsec/pixel: 0.72 Pixels/star: 6.0 + Seeing: 1.5 Airmass: 1.20 Phase: 0.0 + + + Filter Time Mag SNR Star Sky/pix Noise contributions + Star Sky CCD + + U 70.2 20.0 10.0 196.6 8.8 14.02 8.90 10.53 + B 13.0 20.0 10.0 208.8 13.0 14.45 10.82 10.51 + V 13.2 20.0 10.0 250.7 29.8 15.83 16.37 10.51 + R 17.3 20.0 10.0 365.8 95.9 19.13 29.38 10.51 + I 126.4 20.0 10.0 1259.2 1609.8 35.49 120.37 10.55 + + U 1.0 15.6 10.0 166.6 0.1 12.91 1.06 10.50 + B 1.0 17.4 10.0 170.0 1.0 13.04 3.00 10.50 + V 1.0 17.6 10.0 174.6 2.3 13.21 4.50 10.50 + R 1.0 17.6 10.0 186.0 5.5 13.64 7.06 10.50 + I 1.0 16.7 10.0 207.9 12.7 14.42 10.71 10.50 + + U 1.0 20.0 0.3 2.8 0.1 1.67 1.06 10.50 + B 1.0 20.0 1.4 16.0 1.0 4.00 3.00 10.50 + V 1.0 20.0 1.6 19.0 2.3 4.36 4.50 10.50 + R 1.0 20.0 1.6 21.1 5.5 4.59 7.06 10.50 + I 1.0 20.0 0.7 10.0 12.7 3.16 10.71 10.50 + +.fi + +Note that the default of 1 second in the last section +gives the count rates per second for star and sky. + +3. Sometimes one may want to vary one parameter easily on the command +line or query. This can be done by changing the parameter to query +mode. In the following example we want to change the magnitude. + +.nf + cl> ccdtime.magnitude.p_mode=query + cl> ccdtime.telescope="0.9m" + cl> ccdtime.detector="t1ka" + cl> ccdtime.f1=""; ccdtime.f5="" + cl> ccdtime + Magnitude (20.): + Database: ccdtime$kpno.dat Telescope: 0.9m Detector: t1ka + Sum: 1 Arcsec/pixel: 0.72 Pixels/star: 6.0 + Seeing: 1.5 Airmass: 1.20 Phase: 0.0 + + Filter Time Mag SNR Star Sky/pix Noise contributions + Star Sky CCD + + B 13.0 20.0 10.0 208.8 13.0 14.45 10.82 10.51 + V 13.2 20.0 10.0 250.7 29.8 15.83 16.37 10.51 + R 17.3 20.0 10.0 365.8 95.9 19.13 29.38 10.51 + + cl> ccdtime 21 + ... + cl> ccdtime 22 + ... +.fi +.ih +REVISIONS +.ls CCDTIME V2.13 +The f1 to f5 parameters were modified to allow lists of filters so +that more than five filters can be output without changing the parameter +interface. +.le +.ls CCDTIME V2.12 +Task added to OBSUTIL package. +.le +.ls CCDTIME V2.11.4 +A error will be reported if the requested time or SNR is not greater +than zero and less than 100000., or if the absolute value +of the magnitude is greater than 40. +.le +.ls CCDTIME V2.11.2 +The incorrect usage of a 1 mag/airmass extinction was fixed by adding an +expected "extinction" entry in the filter entries. Note that old files +will still give the same result by using an extinction of 1 if the keyword +is not found. + +The database keywords can not be indexed by telescope, filter, and/or +detector. + +The number of pixels per aperture now has a minimum of 9 pixels. +.le +.ih +SEE ALSO +sptime +.endhelp diff --git a/noao/obsutil/src/doc/cgiparse.hlp b/noao/obsutil/src/doc/cgiparse.hlp new file mode 100644 index 00000000..f054ca4e --- /dev/null +++ b/noao/obsutil/src/doc/cgiparse.hlp @@ -0,0 +1,166 @@ +.help cgiparse Mar03 noao.obsutil +.ih +NAME +cgiparse -- parse STRING_QUERY environment var. into parameters +.ih +SYNOPSIS +CGIPARSE parses the STRING_QUERY environment varabile and sets parameters. +The string format is a list of task.param=value pairs which includes the +standard QUERY string special characters '&', '+', and '%'. This is +intended to parse a query from a CGI script. +.ih +USAGE +cgiparse +.ih +PARAMETERS +There are no parameters. The input is the value of the QUERY_STRING +environment variable. +.ih +DESCRIPTION +CGIPARSE parses the STRING_QUERY environment varabile and sets parameters. +The string format is a list of task.param=value pairs which includes the +standard QUERY string special characters '&', '+', and '%'. This is +intended to parse a query from a CGI script. + +The only input is the STRING_QUERY variable. If it is undefined the +task simply does nothing. The string will normally use the standard +parameters for this type of string. The data fields are task.param=value +strings. As each is parsed the values will be set for the task. This +assumes the tasks are defined. Theere is no error checking for +undefined tasks or parameters. +.ih +EXAMPLES +1. A CGI script calls a CL script with the STRING_QUERY string set. +The string has "imheader.longheader=yes". CGIPARSE is called and +when it completes the parameter value is set. + +.nf + cl> lpar imhead + cl> lpar imheader + images = image names + (imlist = "*.imh,*.fits,*.pl,*.qp,*.hhh") default image ... + (longheader = no) print header in multi-line format + (userfields = yes) print the user fields ... + (mode = "ql") + cl> cgiparse + cl> lpar imheader + images = image names + (imlist = "*.imh,*.fits,*.pl,*.qp,*.hhh") default image ... + (longheader = yes) print header in multi-line format + (userfields = yes) print the user fields ... + (mode = "ql") +.fi + +Note that when running this in a "#!cl" script where the "login.cl" is +not used that you must be careful to have all tasks referenced by the +query string defined. + +2. Below is a "#!cl" type script that uses CGIPARSE. It is used for +a spectral exposure time calculator based on OBSUTIL.SPTIME though many +aspects are fairly generic for this type of application. + +.nf +#!/iraf/iraf/bin.freebsd/cl.e -f + +file urldir + +# The following must be set for different hosts. +# The home directory and the urldir are the same but in different syntax. +# The home directory must have a world writable tmp subdirectory. + +set arch = ".freebsd" +set (home = osfn ("/www/htdocs/noao/staff/brooke/gsmt/")) +urldir = "/noao/staff/brooke/gsmt/" + +# The uparm is a unique temporary directory. +s1 = mktemp ("uparm") // "/" +set (uparm = "home$/tmp/" // s1) +mkdir uparm$ +cd uparm +printf ("!/bin/chmod a+rw %s\n", osfn("uparm$")) | cl + +# The URL directory is the same as uparm. +urldir = urldir // "tmp/" // s1 + +# A private graphcap is required to give an path for sgidispatch. +set graphcap = home$graphcap + +# Load packages. +dataio +proto +noao +onedspec +spectime +gsmt + +# Parse the CGI string and set parameters. +cgiparse + +# Create the output. + +# Start HTML. +printf ("Content-Type: text/html\n\n") +printf ("<html><head><title>Test</title></head>\n") +printf ("<body>\n") +if (cl.line == "...") + printf ("<center><h2>SPECTIME</h2></center>\n", cl.line) +else + printf ("<center><h2>%s</h2></center>\n", cl.line) +printf ("<pre>\n") + +# Execute task(s). +#show QUERY_STRING + +setup interactive=no mode=h +printf ("</pre>\n") +printf ("<A Href='http://www.noao.edu/noao/staff/brooke/gsmt/gsmt.php?stage=1'>Back to form</A>") +printf ("<pre>\n") + +sptime output="counts,snr" graphics="g-gif" interactive=no mode=h + +printf ("</pre>\n") +printf ("<A Href='http://www.noao.edu/noao/staff/brooke/gsmt/gsmt.php?stage=1'>Back to form</A>\n") + +printf ("<pre>\n") + +# Add any gifs created. We have to wait for them to be created. + +gflush + +i = 0; j = 1 +while (i != j) { + sleep 2 + j = i + files *.gif | count STDIN | scan (i) +} + + +if (i > 0) { + printf ("<br><p><em>Note: DN and S/N are per-pixel</em><br>\n") + + files *.gif > gifs + list = "gifs" + while (fscan (list, s1) != EOF) { + if (access (s1)) + printf ("<img src=\"%s%s\">\n", urldir, s1) + } + list = "" + ## delete ("uparm$gifs", verify-) +} + +printf ("</pre>\n") + +# Finish HTML. + +printf ("<A Href='http://www.noao.edu/noao/staff/brooke/gsmt/gsmt.php?stage=1'>Back to form</A>") + +printf ("</body></html>\n") + +# Clean up. +## delete ("*[^g][^i][^f]", verify-) + +logout +.fi +.ih +SEE ALSO +.endhelp diff --git a/noao/obsutil/src/doc/findgain.hlp b/noao/obsutil/src/doc/findgain.hlp new file mode 100644 index 00000000..91bf7eaf --- /dev/null +++ b/noao/obsutil/src/doc/findgain.hlp @@ -0,0 +1,168 @@ +.help findgain Nov01 noao.obsutil +.ih +NAME +findgain -- calculate the gain and readout noise of a CCD +.ih +SYNOPSIS +FINDGAIN uses Janesick's method for determining the gain and read noise +in a CCD from a pair of dome flat exposures and a pair of zero frame +exposures (zero length dark exposures). +.ih +USAGE +findgain flat1 flat2 zero1 zero2 +.ih +PARAMETERS +.ls flat1, flat2 +First and second dome flats. +.le +.ls zero1, zero2 +First and second zero frames (zero length dark exposures). +.le +.ls section = "" +The selected image section for the statistics. This should be chosen +to exclude bad columns or rows, cosmic rays and other blemishes, and +the overscan region. The flat field iillumination should be constant +over this section. +.le +.ls center = "mean" +The statistical measure of central tendency that is used to estimate +the data level of each image. This can have the values: \fBmean\fR, +\fBmidpt\fR, or \fBmode\fR. These are calculated using the same +algorithm as the IMSTATISTICS task. +.le +.ls nclip = 3 +Number of sigma clipping iterations. If the value is zero then no clipping +is performed. +.le +.ls lsigma = 4, usigma = 4 +Lower and upper sigma clipping factors used with the mean value and +standard deviation to eliminate cosmic rays. +Since \fBfindgain\fR is sensitive to the statistics of the data the +clipping factors should be symmetric (the same both above and below the +mean) and should not bias the standard deviation. Thus the values should +not be made smaller than around 4 sigma otherwise the gain and readnoise +estimates will be affected. +.le +.ls binwidth = 0.1 +The bin width of the histogram (in sigma) that is used to estimate the +\fBmidpt\fR or \fBmode\fR of the data section in each image. +The default case of center=\fBmean\fR does not use this parameter. +.le +.ls verbose = yes +Verbose output? +.le +.ih +DESCRIPTION +FINDGAIN uses Janesick's method for determining the gain and read noise +in a CCD from a pair of dome flat exposures and a pair of zero frame +exposures (zero length dark exposures). +The task requires that the flats and zeros be unprocessed and uncoadded so +that the noise characteristics of the data are preserved. Note, however, +that the frames may be bias subtracted if the average of many zero frames +is used, and that the overscan region may be removed prior to using this +task. + +Bad pixels should be eliminated to avoid affecting the statistics. +This can be done with sigma clipping and/or an image section. +The sigma clipping should not significantly affect the assumed gaussian +distribution while eliminating outlyers due to cosmic rays and +unmasked bad pixels. This means that clipping factors should be +symmetric and should have values four or more sigma from the mean. +.ih +ALGORITHM +The formulae used by the task are: + +.nf + flatdif = flat1 - flat2 + + zerodif = zero1 - zero2 + + gain = ((mean(flat1) + mean(flat2)) - (mean(zero1) + mean(zero2))) / + ((sigma(flatdif))**2 - (sigma(zerodif))**2 ) + + readnoise = gain * sigma(zerodif) / sqrt(2) +.fi + +where the gain is given in electrons per ADU and the readnoise in +electrons. Pairs of each type of comparison frame are used to reduce +the effects of gain variations from pixel to pixel. The derivation +follows from the definition of the gain (N(e) = gain * N(ADU)) and from +simple error propagation. Also note that the measured variance +(sigma**2) is related to the exposure level and read-noise variance +(sigma(readout)**2) as follows: + +.nf + variance(e) = N(e) + variance(readout) +.fi + +Where N(e) is the number of electrons (above the zero level) in a +given duration exposure. + +In our implementation, the \fBmean\fR used in the formula for the gain +may actually be any of the \fBmean\fR, \fBmidpt\fR (an estimate of the +median), or \fBmode\fR as determined by the \fBcenter\fR parameter. +For the \fBmidpt\fR or \fBmode\fR choices only, the value of the +\fBbinwidth\fR parameter determines the bin width (in sigma) of the +histogram that is used in the calculation. \fBFindgain\fR uses the +\fBimstatistics\fR task to compute the statistics. +.ih +EXAMPLES +To calculate the gain and readnoise within a 100x100 section: + +.nf + ms> findgain flat1 flat2 zero1 zero2 section="[271:370,361:460]" +.fi + +To calculate the gain and readnoise using the mode to estimate the data +level for each image section: + +.nf + ms> findgain.section="[271:370,361:460]" + ms> findgain flat1 flat2 zero1 zero2 center=mode +.fi + +The effects of cosmic rays can be seen in the following example using +artificial noise created with the \fBartdata.mknoise\fR package. The +images have a gain of 5 and a readnoise of 10 with 100 cosmic rays added +over the 512x512 images. The zero level images have means of zero and the +flat field images have means of 1000. The first execution uses the default +clipping and the second turns off the clipping. + +.nf + cl> findgain flat1 flat2 zero1 zero2 + FINDGAIN: + center = mean, binwidth = 0.1 + nclip = 3, lclip = 4., uclip = 4. + + Flats = flat1 & flat2 + Zeros = zero1 & zero2 + Gain = 5.01 electrons per ADU + Read noise = 10.00 electrons + cl> findgain flat1 flat2 zero1 zero2 nclip=0 + FINDGAIN: + center = mean, binwidth = 0.1 + nclip = 0, lclip = 4., uclip = 4. + + Flats = flat1 & flat2 + Zeros = zero1 & zero2 + Gain = 2.86 electrons per ADU + Read noise = 189.5 electrons +.fi + +.ih +BUGS +The image headers are not checked to see if the frames have been +processed. + +There is no provision for finding the "best" values and their errors +from several flats and zeros. +.ih +REVISIONS +.ls FINDGAIN - V2.12 +New task derived from MSCFINDGAIN. This makes use of the new clipping +feature in IMSTATISTICS. +.le +.ih +SEE ALSO +imstatistics +.endhelp diff --git a/noao/obsutil/src/doc/kpnofocus.hlp b/noao/obsutil/src/doc/kpnofocus.hlp new file mode 100644 index 00000000..176a8fe7 --- /dev/null +++ b/noao/obsutil/src/doc/kpnofocus.hlp @@ -0,0 +1,214 @@ +.help kpnofocus Mar96 noao.obsutil +.ih +NAME +kpnofocus -- Determine the best focus from KPNO focus images +.ih +USAGE +kpnofocus images +.ih +PARAMETERS +.ls images +List of focus images. +.le +.ls frame = 1 +The image display is checked to see if the image is already in one of +the display frames. If it is not the \fBdisplay\fR task is called to +display the image in the frame specified by the \fBframe\fR parameter. All +other display parameters are taken from the current settings of the task. +This option requires that the image display be active. +.le + +.ls level = 0.5 +The parameter used to quantify an object image size is the radius from the +image center enclosing the fraction of the total flux given by this +parameter. If the value is greater than 1 it is treated as a percentage. +.le +.ls size = "FWHM" (Radius|FWHM|GFWHM|MFWHM) +There are four ways the PSF size may be shown in graphs and given in +the output. These are: + +.nf + Radius - the radius enclosing the specified fraction of the flux + FWHM - a direct FWHM from the measured radial profile + GFWHM - the FWHM of the best fit Gaussian profile + MFWHM - the FWHM of the best fit Moffat profile +.fi + +The labels in the graphs and output will be the value of this parameter +to distinguish the different types of size measurements. +.le +.ls beta = INDEF +For the Moffat profile fit (size = MFWHM) the exponent parameter may +be fixed at a specified value or left free to be determined from the +fit. The exponent parameter is determined by the fit if \fIbeta\fR +task parameter is INDEF. +.le +.ls scale = 1. +Pixel scale in user units per pixel. Usually the value is 1 to measure +sizes in pixels or the image pixel scale in arc seconds per pixel. +.le +.ls radius = 5., iterations = 2 +Measurement radius in pixels and number of iterations on the radius. The +enclosed flux profile is measured out to this radius. This radius may be +adjusted if the \fIiteration\fR parameter is greater than 1. In that case +after each iteration a new radius is computed from the previous FWHM +estimate to be the radius the equivalent gaussian enclosing 99.5% of the +light. The purpose of this is so that if the initial PSF size of the image +need not be known. However, the radius should then be larger than true +image size since the iterations best converge to smaller values. +.le +.ls sbuffer = 5., swidth = 5. +Sky buffer and sky width in pixels. The buffer is added to the specified +measurement \fIradius\fR to define the inner radius for a circular sky +aperture. The sky width is the width of the circular sky aperture. +.le +.ls saturation=INDEF, ignore_sat=no +Data values (prior to sky subtraction) to be considered saturated within +measurement radius. A value of INDEF treats all pixels as unsaturated. If +a measurement has saturated pixels there are two actions. If +\fIignore_sat\fR=no then a warning is given but the measurement is saved +for use. The object will also be indicated as saturated in the output +log. If \fIignore_sat\fR=yes then a warning is given and the object is +discarded as if it was not measured. In a focus sequence only the +saturated objects are discarded and not the whole sequence. +.le +.ls logfile = "logfile" +File in which to record the final results. If no log file is desired a +null string may be specified. +.le +.ih +CURSOR COMMANDS +When selecting objects with the image cursor the following commands are +available. + +.nf +? Page cursor command summary +g Measure object and graph the results. +m Measure object. +q Quit object marking and go to next image. + At the end of all images go to analysis of all measurements. + +:show Show current results. +.fi + +When in the interactive graphics the following cursor commands are available. +All plots may not be available depending on the number of focus values and +the number of stars. + +.nf +? Page cursor command summary +a Spatial plot at a single focus +b Spatial plot of best focus values +d Delete star nearest to cursor +e Enclosed flux for stars at one focus and one star at all focus +f Size and ellipticity vs focus for all data +i Information about point nearest the cursor +m Size and ellipticity vs relative magnitude at one focus +n Normalize enclosed flux at x cursor position +o Offset enclosed flux to by adjusting background +p Radial profiles for stars at one focus and one star at all focus +q Quit +r Redraw +s Toggle magnitude symbols in spatial plots +t Size and ellipticity vs radius from field center at one focus +u Undelete all deleted points +x Delete nearest point, star, or focus (selected by query) +z Zoom to a single measurement +<space> Step through different focus or stars in current plot type + + +:beta <val> Beta parameter for Moffat fits +:level <val> Level at which the size parameter is evaluated +:overplot <y|n> Overplot the profiles from the narrowest profile? +:radius <val> Change profile radius +:show <file> Page all information for the current set of objects +:size <type> Size type (Radius|FWHM) +:scale <val> Pixel scale for size values +:xcenter <val> X field center for radius from field center plots +:ycenter <val> Y field center for radius from field center plots + +The profile radius may not exceed the initial value set by the task +parameter. +.fi +.ih +DESCRIPTION +This task is a script based on the task \fBstarfocus\fR. The details +of the algorithms and display modes are given in the help for that +task. The purpose of \fBkpnofocus\fR is to provide a simpler task +with fewer parameters because the format of the multiple exposure +images is given by header keywords. + +As a summary of the algorithm, the center of each star image is +found using centroids, a background is determined from the mode +of a sky annulus, and the enclosed flux profile is measured. The +PSF width is then the radius enclose a specified fraction of the +flux. Alternatively a direct FWHM from the radial intensity profile, +a FWHM for a Moffat profile fit to the enclosed flux profile, or +a FWHM for a Gaussian profile fit to the enclosed flux profile may be +used. + +If a saturation value is specified then all pixels within the specified +measurement radius are checked for saturation. If any saturated pixels are +found a warning is given and \fIignore_sat\fR parameter may be used ot +ignore the measurement. If not ignored the object will still be indicated +as saturated in the output log. In a focus sequence only the saturated +objects are discarded and not the whole sequence. + +To use this task consists of specifying a focus image name. Multiple +images could be analyzed together but this is uncommon. The task +will then display the image, using the current parameters of the +\fBdisplay\fR task, if the image is not already in the display. +The user then marks the first exposure (the top one) by pointing +the image cursor and typing 'm'. This may be done for more than +one star if desired. After all stars to be used are marked type +'q' to go to the graphical analysis. + +A plot showing the variation of the PSF width and ellipticity with +focus is shown along with a magnitude weighted, parabolic +interpolated estimate for the best focus. One may delete bad points +with the cursor 'd' key. To exit and record the results to +a logfile use the 'q' key. There are many graphical display +options for more sophisticated analysis such as variations with +position. The best thing to do is to try the various keystroke +commands given in the CURSOR section. For details about +the various plots see the \fBstarfocus\fR help. + +The other task parameters allow setting the enclosed flux level, +the object and sky apertures, and the type and scale of the +reported PSF size. The log filename may also be specified. +.ih +EXAMPLES +1. A multiple exposure frame is taken with 7 exposures of a bright +star, each exposure shifted by 30 pixels using the version of the +ICE software which records the focus information in the keywords +FOCSTART, FOCSTEP, FOCNEXPO, and FOCSHIFT. + +.nf +cl> kpnofocus focus1 +<The image is displayed and the image cursor activated> +<The bright star is marked with 'm'> +<Marking is finished with 'q'> +<A graph of FWHM vs focus is shown> +<Exit with 'q'> +NOAO/IRAF IRAFV2.10.3 valdes@puppis Fri 15:48:01 12-Nov-93 + + Image Column Line Mag Focus FWHM Ellip PA SAT + 36inch1 536.63 804.03 0.07 4660. 13.878 0.06 -11 + 535.94 753.28 -0.12 4680. 8.569 0.09 89 + 535.38 703.96 -0.08 4700. 5.164 0.11 -88 + 537.12 655.36 -0.02 4720. 3.050 0.08 -77 + 534.20 604.59 0.00 4740. 4.336 0.11 74 + 534.41 554.99 -0.00 4760. 9.769 0.09 -35 + 534.83 456.08 0.16 4780. 12.569 0.13 -10 + + Best focus of 4722.44 with FWHM (at 50% level) of 3.02 +.fi + +The estimated best focus is between the 4th and 5th focus setting +at a value of 4722.4 and the best focus FWHM is 3.02 pixels. +.ih +SEE ALSO +.nf +imexamine, implot, pprofile, pradprof, psfmeasure, radlist, +radplt, radprof, ranges, specfocus, splot, starfocus +.endhelp diff --git a/noao/obsutil/src/doc/pairmass.hlp b/noao/obsutil/src/doc/pairmass.hlp new file mode 100644 index 00000000..d271b42b --- /dev/null +++ b/noao/obsutil/src/doc/pairmass.hlp @@ -0,0 +1,132 @@ +.help pairmass Nov01 noao.obsutil +.ih +NAME +pairmass -- plot the airmass for a given object +.ih +USAGE +pairmass +.ih +PARAMETERS +.ls ra +The right ascension of the object in hours. +.le +.ls dec +The declination of the object in degrees. +.le +.ls epoch=INDEF +The epoch of the coordinates in years. +.le +.ls year +The year of the observation. +.le +.ls month +The month of the observation (a number from 1 to 12). +.le +.ls day +The day of the month of the observation. +.le +.ls observatory = "observatory" +The observatory identifier in the observatory database. See the +help for \fBobservatory\fR task for more information. +.le +.ls timesys = "Standard" (Universal|Standard|Siderial) +Time system for the plot or output list. The choices are +"Universal" for universal time, "Standard" for standard time (where +the time zone is determined from the observatory database), and "Siderial" +for the siderial time. +.le + +.ls resolution=4 +The number of UT points per hour for which to calculate the airmass. +.le +.ls listout=no +List, rather than plot, the airmass versus time? Only airmasses +below that given by the \fIwy2\fR parameters are listed. +.le +.ih +PLOT PARAMETERS +.ls wx1=-7., wx2=7., wy1=0., wy2=5. +The range of window (user) coordinates to be included in the plot. +If the range of values in x or y = 0, the plot is automatically +scaled from the minimum to maximum data values along that axis. +The times are available from -24 hours to 48 hours so one can use +negative numbers to plot hours from midnight or in actual hours. +.le +.ls pointmode = no +Plot individual points instead of a continuous line? +.le +.ls marker="box" +If \fBpointmode\fR = yes, the marker drawn at each point is set with this +parameter. The acceptable choices are "point", "box", "plus", "cross", +"circle", "hebar", "vebar", "hline", "vline", and "diamond". +.le +.ls szmarker = 0.005 +The size of the marker drawn when \fBpointmode\fR = yes. A value of 0 +(zero) indicates that the task should read the size from the input list. +.le +.ls logx = no, logy = no +Draw the x or y axis in log units, versus linear? +.le +.ls xlabel="default" +Label for the X-axis. The value "default" uses the specified time system. +.le +.ls ylabel="Airmass" +Labels for the Y-axis. +.le +.ls title="default" +Title for plot. If not changed from "default", a title string consisting +of the date, observatory, and object position is used. +.le +.ls vx1=0., vx2=0., vy1=0., vy2=0. +NDC coordinates (0-1) of the plotting device viewport. If not set +by the user, a suitable viewport which allows sufficient room for all +labels is used. +.le +.ls majrx=5, minrx=5, majry=5, minry=5 +The number of major and minor divisions along the x or y axis. +.le +.ls round = no +Round axes up to nice values? +.le +.ls fill = yes +Fill the plotting viewport regardless of the device aspect ratio? +.le +.bp +.ls append = no +Append to an existing plot? +.le +.ls device="stdgraph" +Output device. +.le +.ih +DESCRIPTION +The airmass is plotted over a specified set of hours for a given +observatory. The observatory is specified by an identifier as given +in the observatory database. See the help for "observatory" for more +information about the database and identifiers. + +The results can be shown in universal, standard, or siderial time. +The standard time simply adds the time zone from the observatory +database tothe universal time and so there is no explicit facility +for daylight savings time. The times are computed in the range +-24 hours to +48 hours. By setting the \fIwx1\fR and \fIwx2\fR +parameters one can plot either in hours relative to 0 in the specified +time system or as positive hours. This simple task does not support +axis labeling which wraps around. + +The list output prints date, observatory, object coordinates, and +the time system. This is followed by the time sorted between 0 and 24 +and the airmasses. The list only includes airmasses below the +value specified by \fIwy2\fR. +.ih +EXAMPLES +To plot the airmass for M82 from Kitt Peak for Groundhog's Day in 1992: + +.nf + pairmass ra=9:51:42 dec=69:56 epoch=1950 year=1992 month=2 day=2 +.fi + +.ih +SEE ALSO +observatory, airmass, setairmass, graph +.endhelp diff --git a/noao/obsutil/src/doc/psfmeasure.hlp b/noao/obsutil/src/doc/psfmeasure.hlp new file mode 100644 index 00000000..479268b1 --- /dev/null +++ b/noao/obsutil/src/doc/psfmeasure.hlp @@ -0,0 +1,633 @@ +.help psfmeasure Nov01 noao.obsutil +.ih +NAME +psfmeasure -- Measure PSF widths in stellar images +.ih +USAGE +psfmeasure images +.ih +PARAMETERS +.ls images +List of images. +.le +.ls coords = "mark1" (center|mark1|markall) +Method by which the coordinates of objects to be measured are specified. +If "center" then a single object at the center of each image is measured. +If "mark1" then the \fIimagecur\fR parameter, typically the interactive +image display cursor, defines the coordinates of one or more objects in the +first image ending with a 'q' key value and then the same coordinates are +automatically used in subsequent images. If "markall" then the +\fIimagecur\fR parameter defines the coordinates for objects in each image +ending with a 'q' key value. +.le +.ls wcs = "logical" (logical|physical|world) +Coordinate system for input coordinates. When using image cursor input +this will always be "logical". When using cursor input from a file this +could be "physical" or "world". +.le +.ls display = yes, frame = 1 +Display the image or images as needed? If yes the image display is checked +to see if the image is already in one of the display frames. If it is not +the \fBdisplay\fR task is called to display the image in the frame +specified by the \fBframe\fR parameter. All other display parameters are +taken from the current settings of the task. This option requires that the +image display be active. A value of no is typically used when an input +cursor file is used instead of the image display cursor. An image display +need not be active in that case. +.le + +.ls level = 0.5 +The parameter used to quantify an object image size is the radius from the +image center enclosing the fraction of the total flux given by this +parameter. If the value is greater than 1 it is treated as a percentage. +.le +.ls size = "FWHM" (Radius|FWHM|GFWHM|MFWHM) +There are four ways the PSF size may be shown in graphs and given in +the output. These are: + +.nf + Radius - the radius enclosing the specified fraction of the flux + FWHM - a direct FWHM from the measured radial profile + GFWHM - the FWHM of the best fit Gaussian profile + MFWHM - the FWHM of the best fit Moffat profile +.fi + +The labels in the graphs and output will be the value of this parameter +to distinguish the different types of size measurements. +.le +.ls beta = INDEF +For the Moffat profile fit (size = MFWHM) the exponent parameter may +be fixed at a specified value or left free to be determined from the +fit. The exponent parameter is determined by the fit if \fIbeta\fR +task parameter is INDEF. +.le +.ls scale = 1. +Pixel scale in user units per pixel. Usually the value is 1 to measure +sizes in pixels or the image pixel scale in arc seconds per pixel. +.le +.ls radius = 5., iterations = 3 +Measurement radius in pixels and number of iterations on the radius. The +enclosed flux profile is measured out to this radius. This radius may be +adjusted if the \fIiteration\fR parameter is greater than 1. In that case +after each iteration a new radius is computed from the previous direct FWHM +estimate. The new radius is three times direct FWHM (six times the +half-maximum radius). The purpose of this is so that if the initial PSF +size of the image need not be known. However, the radius should then be +larger than true image size since the iterations best converge to smaller +values. +.le +.ls sbuffer = 5, swidth = 5. +Sky buffer and sky width in pixels. The buffer is added to the specified +measurement \fIradius\fR to define the inner radius for a circular sky +aperture. The sky width is the width of the circular sky aperture. +.le +.ls saturation=INDEF, ignore_sat=no +Data values (prior to sky subtraction) to be considered saturated within +measurement radius. A value of INDEF treats all pixels as unsaturated. If +a measurement has saturated pixels there are two actions. If +\fIignore_sat\fR=no then a warning is given but the measurement is saved +for use. The object will also be indicated as saturated in the output +log. If \fIignore_sat\fR=yes then a warning is given and the object is +discarded as if it was not measured. +.le +.ls xcenter = INDEF, ycenter = INDEF +The optical field center of the image given in image pixel coordinates. +These values need not lie in the image. If INDEF the center of the image +is used. These values are used to make plots of size verse distance from +the field center for studies of radial variations. +.le +.ls logfile = "logfile" +File in which to record the final results. If no log file is desired a +null string may be specified. +.le + +.ls imagecur = "" +Image cursor input for the "mark1" and "markall" options. If null then the +image dispaly cursor is used interactively. If a file name is specified +then the coordinates come from this file. The format of the file are lines +of x, y, id, and key. Values of x an y alone may be used to select objects +and the single character 'q' (or the end of the file) may be used to end +the list. +.le +.ls graphcur = "" +Graphics cursor input. If null then the standard graphics cursor +is used otherwise a standard cursor format file may be specified. +.le +.ih +CURSOR COMMANDS +When selecting objects with the image cursor the following commands are +available. + +.nf +? Page cursor command summary +g Measure object and graph the results. +m Measure object. +q Quit object marking and go to next image. + At the end of all images go to analysis of all measurements. + +:show Show current results. +.fi + +When in the interactive graphics the following cursor commands are available. +All plots may not be available depending on the number of stars. + +.nf +? Page cursor command summary +a Spatial plot +d Delete star nearest to cursor +e Enclosed flux for all stars +i Information about star nearest the cursor +m Size and ellipticity vs relative magnitude +n Normalize enclosed flux at x cursor position +o Offset enclosed flux by adjusting background +p Radial profiles for all stars +q Quit +r Redraw +s Toggle magnitude symbols in spatial plot +t Size and ellipticity vs radius from field center +u Undelete all deleted points +x Delete nearest point or star (selected by query) +z Zoom to a single measurement +<space> Step through different stars in some plots + +:beta <val> Set the beta parameter for the Moffat profile fit +:level <val> Level at which the size parameter is evaluated +:overplot <y|n> Overplot the profiles from the narrowest profile? +:radius <val> Change profile radius +:show <file> Page all information for the current set of objects +:size <type> Size type (Radius|FWHM) +:scale <val> Pixel scale for size values +:xcenter <val> X field center for radius from field center plots +:ycenter <val> Y field center for radius from field center plots +.fi +.ih +DESCRIPTION +This task measures the point-spread function (PSF) width of stars or other +unresolved objects in digital images. The width is measured from the +enclosed flux verses radius profile. The details of this are described in +the ALGORITHMS section. Measurements of multiple stars in multiple images +may be made. When there are multiple stars, variations in the PSF with +position may be examined. The task has three stages; selecting objects and +measuring the PSF width and other parameters, an interactive graphical +analysis, and a final output of the results to the terminal and to a +logfile. + +If a saturation value is specified then all pixels within the specified +measurement radius are checked for saturation. If any saturated pixels are +found a warning is given and \fIignore_sat\fR parameter may be used ot +ignore the measurement. If not ignored the object will still be indicated +as saturated in the output log. In a focus sequence only the saturated +objects are discarded and not the whole sequence. + +The input images are specified by an image template list. The list may +consist of explicit image names, wildcard templates, and @ files. +Identifying the object or objects to be measured may be accomplished in +several ways. If a single object near the center of the image is to be +measured then the \fIcoords\fR parameter takes the value "center". When +the "center" option is used the \fIdisplay\fR and \fIimagecur\fR parameters +are ignored. + +If there are multiple objects or the desired object is not at the center of +the frame the object coordinates are entered with the \fIimagecur\fR +parameter. This type of coordinate input is selected by specifying either +"mark1" or "markall" for the \fIcoords\fR parameter. If the value is +"mark1" then the coordinates are entered for the first image and the same +values are automatically used for subsequent images. If "markall" is +specified then the objects in each image are marked. + +Normally the \fIimagecur\fR parameter would select the interactive image +display cursor though a standard cursor file could be used to make this +part noninteractive. When the image display cursor is used either the +image must be displayed previously by the user, or the task may be allowed +to load the image display using the \fBdisplay\fR task by setting the +parameter \fIdisplay\fR to yes and \fIframe\fR to a display frame. If yes +the image display must be active. The task will look at the image names as +stored in the image display and only load the display if needed. + +If one wants to enter a coordinate list rather than use the interactive +image cursor the list can consist of just the column and line coordinates +since the key will default to 'm'. To finish the list either the end +of file may be encountered or a single 'q' may be given since the +coordinates are irrelevant. For the "markall" option with multiple +images there would need to be a 'q' at the end of each object except +possibly the last. + +When objects are marked interactively with the image cursor there +are a four keys which may be used as shown in the CURSOR COMMAND section. +The important distinction is between 'm' to mark and measure an +object and 'g' to mark, measure, and graph the results. The former +accumulates the results until the end while the latter can give an +immediate result to be examined. Unless only one object is marked +the 'g' key also accumulates the results for later graphical analysis. +It is important to note that the measurements are done as each +object is marked so there can be a significant delay before the +next object may be marked. + +The quantities measured and the algorithms used are described in the +ALGORITHMS section. Once all the objects have been measured an +interactive (unless only one object is measured) graphical presentation +of the measurements is entered. + +When the task exits it prints the results to the terminal (STDOUT) and also +to the \fIlogfile\fR if one is specified. The results may also be +previewed during the execution of the task with the ":show" command. The +results begin with a banner and the overall estimate of the PSF size. +Following this the individual measurements are given. The columns give the +image name, the column and line position, the relative magnitude, the PSF +size as either the enclosed flux radius or the various FWHM, the +ellipticity, and the position angle. +.ih +ALGORITHMS +The PSF of an object is characterized using a radially symmetric +enclosed flux profile. First the center of the object is determined from +an initial rough coordinate. The center is computed from marginal profiles +which are sums of lines or columns centered at the initial coordinate and +with a width given by the sum of the \fIradius\fR, \fIsbuffer\fR, and +\fIswidth\fR parameters. The mean of the marginal profile is determined +and then the centroid of the profile above this is computed. The centroids +from the two marginal profiles define a new object center. These steps of +forming the marginal profiles centered at the estimated object position and +then computing the centroids are repeated until the centroids converge or +three iterations have been completed. + +Next a background is determined from the mode of the pixel values in the +sky annulus defined by the object center and \fIradius\fR, \fIsbuffer\fR, +and \fIswidth\fR parameters. The pixel values in the annulus are sorted +and the mode is estimated as the point of minimum slope in this sorted +array using a width of 5% of the number of points. If there are multiple +regions with the same minimum slope the lowest pixel value is used. + +The background subtracted enclosed flux profile is determined next. +To obtain subpixel precision and to give accurate estimates for small +widths relative to the pixel sampling, several things are done. +First interpolation between pixels is done using a cubic spline surface. +The radii measured are in subpixel steps. To accommodate small and +large PSF widths (and \fIradius\fR parameters) the steps are nonuniform +with very fine steps at small radii (steps of 0.05 pixels in the +central pixel) and coarser steps at larger radii (beyond 9 pixels +the steps are one pixel) out to the specified \fIradius\fR. Similarly each +pixel is subsampled finely near the center and more coarsely at larger +distances from the object center. Each subpixel value, as obtained by +interpolation, is background subtracted and added into the enclosed flux +profile. Even with subpixel sampling there is still a point where a +subpixel straddles a particular radius. At those points the fraction of +the subpixel dimension in radius falling within the radius being measured +is used as the fraction of the pixel value accumulated. + +Because of errors in the background determination due to noise and +contaminating objects it is sometimes the case that the enclosed flux +is not completely monotonic with radius. The enclosed flux +normalization, and the magnitude used in plots and reported in +results, is the maximum of the enclosed flux profile even if it +occurs at a radius less than the maximum radius. It is possible +to change the normalization and subtract or add a background correction +interactively. + +Because a very narrow PSF will produce significant errors in the cubic +spline interpolation due to the steepness and rapid variation in the pixel +values near the peak, the Gaussian profile with FWHM that encloses the same +80% of the flux is computed as: + + FWHM(80%) = 2 * r(80%) * sqrt (ln(2) / (ln (1/.2))) + +If this is less than five pixels the Gaussian model is subtracted from the +data. The Gaussian normalization is chosed to perfectly subtract the +central pixel. The resulting subtraction will not be perfect but the +residual data will have much lower amplitudes and variations. A spline +interpolation is fit to this residual data and the enclosed flux profile is +recomputed in exactly the same manner as previously except the subpixel +intensity is evaluated as the sum of the analytic Gaussian and the +interpolation to the residual data. + +The Gaussian normalization is chosed to perfectly subtract the central +pixel. The resulting subtraction will not be perfect but the residual data +will have much lower amplitudes and variations. A spline interpolation is +fit to this residual data and the enclosed flux profile is recomputed in +exactly the same manner as previously except the subpixel intensity is +evaluated as the sum of the analytic Gaussian and the interpolation to the +residual data. This technique yields accurate FWHM for simulated Gaussian +PSFs down to at least a FWHM of 1 pixel. + +In addition to the enclosed flux profile, an estimate of the radially +symmetric intensity profile is computed from the enclosed flux profile. +This is based on the equation + +.nf + F(R) = integral from 0 to R { P(r) r dr } +.fi + +where F(R) is the enclosed flux at radius R and P(r) is the intensity per +unit area profile. Thus the derivative of F(R) divided by R gives an +estimate of P(R). + +Cubic spline interpolation functions are fit to the normalized enclosed +flux profile and the intensity profile. These are used to find the radius +enclosing any specified fraction of the flux and to find the direct FWHM of +the intensity profile. These are output when \fIsize\fR is "Radius" or +"FWHM" respectively. + +In addition to enclosed flux radius and direct FWHM size measurements +there are also two size measurements based on fitting analytic profiles. +A Gaussian profile and a Moffat profile are fit to the final enclosed flux +profile to the points with enclosed flux less than 80%. The limit is +included to minimize the effects of poor background values and to make the +profile fit be representative of the core of the PSF profile. These profiles +are fit whether or not the selected \fIsize\fR requires it. This is done +for simplicity and to allow quickly changing the size estimate with the +":size" command. + +The intensity profile functions (with unit peak) are: + +.nf + I(r) = exp (-0.5 * (r/sigma)**2) Gaussian + I(r) = (1 + (r/alpha)**2)) ** (-beta) Moffat +.fi + +with parameters sigma, alpha, and beta. The normalized enclosed flux +profiles, which is what is actually fit, are then: + +.nf + F(r) = 1 - exp (-0.5 * (r/sigma)**2) Gaussian + F(r) = 1 - (1 + (r/alpha)**2)) ** (1-beta) Moffat +.fi + +The fits determine the parameters sigma or alpha and beta (if a +beta value is not specified by the users). The reported FWHM values +are given by: + +.nf + GFWHM = 2 * sigma * sqrt (2 * ln (2)) Gaussian + MFWHM = 2 * alpha * sqrt (2 ** (1/beta) - 1) Moffat +.fi + +were the units are adjusted by the pixel scale factor. + +In addition to the four size measurements there are several additional +quantities which are determined. +Other quantities which are computed are the relative magnitude, +ellipticity, and position angle. The magnitude of an individual +measurement is obtained from the maximum flux attained in the enclosed +flux profile computation. Though the normalization and background may be +adjusted interactively later, the magnitude is not changed from the +initial determination. The relative magnitude of an object is then +computed as + +.nf + rel. mag. = -2.5 * log (object flux / maximum star flux) +.fi + +The maximum star magnitude over all stars is used as the zero point for the +relative magnitudes (hence it is possible for an individual object relative +magnitude to be less than zero). + +The ellipticity and positional angle of an object are derived from the +second central intensity weighted moments. The moments are: + +.nf + Mxx = sum { (I - B) * x * x } / sum { I - B } + Myy = sum { (I - B) * y * y } / sum { I - B } + Mxy = sum { (I - B) * x * y } / sum { I - B } +.fi + +where x and y are the distances from the object center, I is +the pixel intensity and B is the background intensity. The sum is +over the same subpixels used in the enclosed flux evaluation with +intensities above an isophote which is slightly above the background. +The ellipticity and position angles are derived from the moments +by the equations: + +.nf + M1 = (Mxx - Myy) / (Mxx + Myy) + M2 = 2 * Mxy / (Mxx + Myy) + ellip = (M1**2 + M2**2) ** 1/2 + pa = atan (M2 / M1) / 2 +.fi + +where ** is the exponentiation operator and atan is the arc tangent +operator. The ellipticity is essentially (a - b) / (a + b) where a +is a major axis scale length and b is a minor axis scale length. A +value of zero corresponds to a circular image. The position angle is +given in degrees counterclockwise from the x or column axis. + +The overall size when there are multiple stars is estimated by averaging +the individual sizes weighted by the flux of the star as described above. +Thus, when there are multiple stars, the brighter stars are given greater +weight in the average size. This average size is what is given in the +banner for the graphs and in the printed output. + +One of the quantities computed for the graphical analysis is the +FWHM of a Gaussian or Moffat profile that encloses the same flux +as the measured object as a function of the level. The equation are: + +.nf + FWHM = 2 * r(level) * sqrt (ln(2.) / ln (1/(1-level))) Gaussian + + FWHM = 2 * r(level) * sqrt (2**(1/beta)-1) / + sqrt ((1-level)**(1/(1-beta))-1) Moffat +.fi + +where r(level) is the radius that encloses "level" fraction of the total +flux. ln is the natural logarithm and sqrt is the square root. The beta +value is either the user specified value or the value determined by fitting +the enclosed flux profile. + +This function of level will be a constant if the object profile matches +the Gaussian or Moffat profile. Deviations from a constant show +the departures from the profile model. The Moffat profile used in making +the graphs except for the case where the \fIsize\fR is GFWHM. +.ih +INTERACTIVE GRAPHICS MODE +The graphics part of \fBpsfmeasure\fR consists of a number of different +plots selected by cursor keys. The available plots depend on the number of +stars. The various plots and the keys which select them are summarized +below. + +.nf +a Spatial plot +e Enclosed flux for all stars +m Size and ellipticity vs relative magnitude +p Radial profiles for all stars +t Size and ellipticity vs radius from field center +z Zoom to a single measurement +.fi + +If there is only one object the only available plot is +the 'z' or zoom plot. This has three graphs; a graph of the normalized +enclosed flux verses scaled radius, a graph of the intensity profile verses +scaled radius, and equivalent Moffat/Gaussian full width at half maximum verses +enclosed flux fraction. The latter two graphs are derived from the +normalized enclosed flux profile as described in the ALGORITHMS section. +In the graphs the measured points are shown with symbols, a smooth curve is +drawn through the symbols and dashed lines indicate the measurement level +and enclosed flux radius at that level. + +Overplotted on these graphs are the Moffat profile fit or the +Gaussian profile fit when \fIsize\fR is GFWHM. + +The zoom plot is always available from any other plot. The cursor position +when the 'z' key is typed selects a particular object measurement. +This plot is also the one presented with the 'g' key when marking objects for +single exposure images. In that case the graphs are drawn followed by +a return to image cursor mode. + +There are two types of symbol plots showing the measured PSF size (either +enclosed flux radius or FWHM) and ellipticity. These plot the measurements +verses relative magnitude ('m' key) and radius from the field center ('t' +key). These plots are only available when there are multiple stars +measured. The magnitude plot is the initial plot in this case. The field +center for the field radius graph may be changed interactively using the +":xcenter" and ":ycenter" commands. + +Grids of enclosed flux vs. radius, intensity profile vs. radius, and +FWHM vs. enclosed flux fraction are shown with the 'e', 'p', and +'g' keys respectively when there is more than one star. The grid shows +a profile for each star. The profiles in the grid have no axis labels or +ticks. Within each box are the coordinates of the object +and the PSF size. Below the grid is shown a graph of a single objects +including axis labels and ticks. + +In the grid there is one profile which is highlighted (by a second box or +by a color border). This is the profile shown in the lower graph. To +change the star in the lower graph on can type the space bar to advance to +the next star or use the cursor and the 'e', 'p', or 'g' key again. Other +keys will select another plot using the star nearest the cursor to select a +measurement. + +Any of the graphs with enclosed flux or intensity profiles vs radius may +have the profiles of the object with the smallest size overplotted. The +overplot has a dashed line, a different color on color graphics devices, +and no symbols marking the measurement points. The overplots may be +enabled or disabled with the ":overplot" command. Initially it is +disabled. + +The final plot, the 'a' key, gives a spatial representation. This requires +more than one star. This plot has a central graph of column and line +coordinates with symbols indicating the position of an object. The objects +are marked with a circle (when plotted at unit aspect ratio) whose size is +proportional to the measured PSF size. In addition an optional asterisk +symbol with size proportional to the relative brightness of the object may +be plotted. This symbol is toggled with the 's' key. On color displays +the circles may have two colors, one if object size is above the average +best size and the other if the size is below the best size. The purpose of +this is to look for a spatial pattern in the PSF sizes. + +Adjacent to the central graph are graphs with column or line as one +coordinate and radius or ellipticity as the other. The symbols +are the same as described previously. These plots can show spatial +gradients in the PSF size and shape across the image. + +In addition to the keys which select plots there are other keys which +do various things. These are summarized below. + +.nf +? Page cursor command summary +d Delete star nearest to cursor +i Information about point nearest the cursor +n Normalize enclosed flux at x cursor position +o Offset enclosed flux by adjusting background +q Quit +r Redraw +s Toggle magnitude symbols in spatial plots +u Undelete all deleted points +x Delete nearest point or star (selected by query) +<space> Step through different stars in current plot type +.fi + +The help, redraw, and quit keys are provide the standard functions. +The 's' and space keys were described previously. The 'i' key +locates the nearest object to the cursor in whatever plot is shown and +prints one line of information about the object on the graphics device +status area. + +The 'd' key deletes the star nearest the cursor in whatever plot is +currently displayed. To delete all objects from an image, all +values for one star (the same as 'd'), or a +single measurement, the 'x' key is used. Typing this key produces a query +for which type of deletion and the user responds with 'i', 's', or +'p'. Deleted measurements do not appear in any subsequent +graphics, are excluded from all computations, and are not output in the +results. The 'u' key allows one to recover deleted measurements. This +undeletes all previously deleted data. + +Due to various sources of error the sky value may be wrong causing +the enclosed flux profile to not converge properly but instead +decreases beyond some point (overestimated sky) or linearly +increases with radius (underestimated sky). This affects the size +measurement by raising or lowering the normalization and altering +the shape of the enclosed flux profile. The 'n' and 'o' keys allow +fudging the enclosed flux profiles. These keys apply only in +the zoom plot or 'e' key plot of the enclosed flux profile. + +The 'n' key normalizes the enclosed flux profile at the point +set by the x position of the cursor. The 'o' key increases or +decreases the background estimate to bring curve up or down to +the point specified by the cursor. The effect of this is to +add or subtract a quadratic function since the number of pixels +at a particular radius varies as the square of the radius. +To restore the original profile, type 'n' or 'o' at a radius +less than zero. + +The colon commands, shown below, allow checking or changing parameters +initially set by the task parameters, toggling the overplotting of the +smallest PSF profiles, and showing the current results. The overplotting +option and the contents of the results displayed by :show were described +previously. + +.nf +:beta <val> Beta value for Moffat profile fits +:level <val> Level at which the size parameter is evaluated +:overplot <y|n> Overplot the profiles from the narrowest profile? +:radius <val> Change profile radius +:show <file> Page all information for the current set of objects +:size <type> Size type (Radius|FWHM) +:scale <val> Pixel scale for size values +:xcenter <val> X field center for radius from field center plots +:ycenter <val> Y field center for radius from field center plots +.fi + +The important values which one might want to change interactively are +the measurement level and the profile radius. The measurement level +directly affects the results reported. When it is changed the sizes +of all object PSFs are recomputed and the displayed plots and title +information are updated. The profile radius is the +maximum radius shown in plots and used to set the enclosed flux normalization. +It does not affect the object centering or sky region definition and +evaluation which are done when the image data is accessed. Because +the objects are not remeasured from the image data the radius may +not be made larger than the radius defined by the task parameter though +it may be decreased and then increased again. +.ih +EXAMPLES +1. An image of a star field is studied with default values. + +.nf +cl> psfmeasure field1 +<The image is displayed and the image cursor activated> +<A number of brighter stars are marked> +<Marking is finished with 'q'> +<Graph of FWHM and ellipticity vs relative magnitude are shown> +<A couple of bad measurements due to blending are deleted> +<Exit with 'q'> +NOAO/IRAF IRAFV2.10.3 valdes@puppis Tue 18:22:36 06-Jul-93 + Average full width at half maximum of 4.5722 + + Image Column Line Mag FWHM Ellip PA SAT + field1 68.96 37.87 0.75 5.636 0.03 15 + 488.41 116.78 1.61 5.376 0.03 -68 + 72.17 156.35 1.47 4.728 0.06 -14 + 33.72 211.86 2.74 4.840 0.05 -52 + 212.80 260.73 2.99 3.888 0.11 83 + 250.51 277.37 1.92 3.914 0.02 -14 + 411.81 292.83 1.93 5.032 0.04 34 + 131.85 301.12 2.67 4.028 0.06 4 + 168.37 413.70 2.20 4.408 0.05 75 + 256.02 255.99 0.00 3.940 0.00 -70 + +The estimated average FWHM is 4.5722. The variation in size is real +in this artificial image having a radial variation in PSF. +.ih +SEE ALSO +.nf +imexamine, implot, pprofile, pradprof, radlist, radplt, radprof, +specfocus, starfocus, splot +.endhelp diff --git a/noao/obsutil/src/doc/shutcor.hlp b/noao/obsutil/src/doc/shutcor.hlp new file mode 100644 index 00000000..6968bdff --- /dev/null +++ b/noao/obsutil/src/doc/shutcor.hlp @@ -0,0 +1,93 @@ +.help shutcor Nov01 noao.obsutil +.ih +NAME +shutcor -- shutter correction from images of varying exposure +.ih +SYNOPSIS +SHUTCOR calculate the shutter correction for a detector given a +sequence of overscan corrected images of varying durations. Typically +these would be flat field exposures. The shutter correction is the +intercept on a plot of exposure duration versus exposure level. +.ih +USAGE +shutcor images +.ih +PARAMETERS +.ls images +List of overscan corrected images. These would usually be flat +field exposures. +.le +.ls section = "" +The selected image section for the statistics. This should be chosen +to exclude bad columns or rows, cosmic rays, and other non-linear +features. +.le +.ls center = "mode" +The statistical measure of central tendency that is used to estimate +the data level of each image. This can have the values: \fBmean\fR, +\fBmidpt\fR, or \fBmode\fR. These are calculated using the same +algorithm as the IMSTATISTICS task. +.le +.ls nclip = 3 +Number of sigma clipping iterations. If the value is zero then no clipping +is performed. +.le +.ls lsigma = 4, usigma = 4 +Lower and upper sigma clipping factors used with the mean value and +standard deviation to eliminate cosmic rays. +Since \fBfindgain\fR is sensitive to the statistics of the data the +clipping factors should be symmetric (the same both above and below the +mean). +.le +.ls exposure = "exptime" +Keyword giving the exposure time. +.le +.ls verbose = yes +Verbose output? +.le +.ih +DESCRIPTION +SHUTCOR calculate the shutter correction for a detector given a +sequence of overscan corrected images of varying durations. Typically +these would be flat field exposures. The shutter correction is the +intercept on a plot of exposure duration versus exposure level. + +The images must contain the keyword OVERSCAN otherwise and error will +be given. + +Bad pixels should be eliminated to avoid affecting the statistics. +This can be done with sigma clipping and/or an image section. +The sigma clipping should not significantly affect the assumed gaussian +distribution while eliminating outlyers due to cosmic rays and +unmasked bad pixels. This means that clipping factors should be +symmetric. +.ih +EXAMPLES +A sequence of flat fields with varying exposure times are taken and +processed to subtract the overscan. + +.nf + cl> shutcor flat* + + Shutter correction = 0.538 +/- 0.043 seconds + + Information about the mode versus exptime fit: + + intercept slope (and errors) + 5.347105 9.933618 + 0.4288701 0.01519613 + + chi sqr: 0.2681 ftest: 419428. correlation: 1. + nr pts: 4. std dev res: 0.422769 + + x(data) y(calc) y(data) sigy(data) + 3. 35.148 34.6725 0. + 12. 124.551 125.015 0. + 27. 273.555 273.778 0. + 48. 482.161 481.949 0. +.fi +.le +.ih +SEE ALSO +imstatistics +.endhelp diff --git a/noao/obsutil/src/doc/specfocus.hlp b/noao/obsutil/src/doc/specfocus.hlp new file mode 100644 index 00000000..137eca23 --- /dev/null +++ b/noao/obsutil/src/doc/specfocus.hlp @@ -0,0 +1,375 @@ +.help specfocus Nov01 noao.obsutil +.ih +NAME +specfocus -- Determine spectral focus and alignment variations +.ih +USAGE +specfocus images +.ih +PARAMETERS +.ls images +List of 1D or 2D focus images. Typically the input is a list of raw +2D CCD images of arc slit spectra. The 1D image input is provided to +allow use of extraction techniques beyond those provided by this task. +.le +.ls focus = "" +List of focus identification values to be associated with each input image +or an image header keyword containing the values. The list may be an +explicit list of values, a range specification, an @ file containing the +values, or an image header keyword. If none of these is given the +identification values are simple index values in the order of the input +images. A range specification has the forms A, AxC, A-BxC where A is a +starting value, B is an ending value, and C is an increment. +.le +.ls corwidth = 20. +Correlation width in pixels. +.le +.ls level = 0.5 +Percent or fraction of the correlation peak at which to measure focus +widths. The default is 50% or full width at half maximum. +.le +.ls shifts = yes +Compute dispersion shifts across the dispersion when there are multiple +samples? If yes and there are multiple samples across the dispersion +(\fIndisp\fR > 1), pixel shifts relative to the central sample are +determine by crosscorrelation. +.le + +.ls dispaxis = 2 +Dispersion axis for 2D images. The image header keyword DISPAXIS has +precedence over this value. +.le +.ls nspectra = 1, ndisp = 1 +The number of spectral samples across the dispersion +and the number of subpieces along the dispersion to divide the spectra +into. If \fInspectra\fR is greater than one then information about +variations across the dispersion will be determined and if \fIndisp\fR is +greater than 1 information about variations along the dispersion will be +determined. \fINspectra\fR applies only to 2D images. For 1D spectra in +multispec format each line is used as a separate sample. +.le +.ls slit1 = INDEF, slit2 = INDEF +The lower and upper edges of the slit (or data region) in pixel +coordinates (lines or columns) across the dispersion axis. A value +of INDEF specifies the image edges. +.le + +.ls logfile = "logfile" +File in which to record the results. If no file is specified no log +output is produced. +.le +.ih +CURSOR COMMANDS +All keys select an image and a sample (one of the \fIndisp\fR samples along +the dispersion and one of the \fInspectra\fR samples across the dispersion) +which is then generally highlighted. + +.nf + ? Help summary + b Best focus at each sample summary graphs + d Delete image, sample, or point + p Profiles at one sample for all images and all samples for one image + q Quit + r Redraw + s Spectra at one sample for all images and all samples for one image + u Undelete spectrum, sample, or point + w Profile widths verses focus and distribution of widths + z Zoom on a single sample showing correlation profile and spectrum + <space> Status line output for selected image and sample +.fi + +.ih +DESCRIPTION +This task estimates the dispersion width of spectral lines in sequences of +arc spectra taken at different focus settings (or with some other parameter +varied). The widths can be measured at different spatial and dispersion +positions, called "samples", on the detector. The width estimates are +recorded and displayed graphically to investigate dependencies and +determine appropriate settings for the spectrograph setup. The task may +also measure dispersion shifts when multiple spectral samples are +specified. This task does not measure the focus point-spread-function +width across the dispersion. + +The input images are specified with an image template list. The list may +consist of explicit image names, wildcard templates, and @ files. A +"focus" value is associated with each image. This may be any numeric +quantity (integer or floating point). The focus values may be specified in +several ways. If no value is given then index numbers are assigned to +the images in the order in which they appear in the image list. A range +list may be specified as described in the help topic \fBranges\fR. This +consists of individual values, ranges of values, a starting value and a +step, and a range with a step. The elements of the list are separated by +commas, ranges are separated by hyphens, and a step is indicated by the +character 'x'. Long range lists, such as a list of individual focus +values, may be placed in a file and specified with the @<filename> +convention. Finally, a parameter in the image header may be used for the +focus values by simply specifying the parameter name. + +Two dimensional long slit images are summed into one or more one +dimensional spectra across the dispersion. The dispersion axis is defined +either by the image header parameter DISPAXIS or the \fIdispaxis\fR task +parameter with the image header parameter having precedence. The range of +lines or columns across the dispersion to be used is specified by the +parameters \fIslit1\fR and \fIslit2\fR. If specified as INDEF then the +image limits are used. This range is then divided into the number of +spectra given by the parameter \fInspectra\fR. Use of more than one +spectrum across the dispersion allows investigation of variations along the +slit. In addition, if the parameter \fIshifts\fR is set the spectrum +nearest the center is used as a reference against which shifts in the +dispersion positions of the features in the other spectra are determined by +crosscorrelation. + +The conversion of two dimensional spectra to one dimensional spectra may +also be performed separately using the tasks in the \fBapextract\fR +package. This would be done typically for multifiber or echelle format +spectra. If the two dimensional spectra have been extracted to one +dimensional spectra in this way the task ignores the dispersion axis and +number of spectra parameters. The data limits (\fIslit1\fR and +\fIslit2\fR) are still used to select a range of lines in "multispec" +format images. The \fIshifts\fR parameter also applies when there are +multiple spectra per image. However, it does not make sense in the case of +echelle spectra and so it should be set to no in that case. + +In addition to dividing the spatial axis into a number of spectra the +dispersion axis may also be divided into a set of subspectra. The number +of divisions is specified by the \fIndisp\fR parameter which applies to +both long slit and 1D extracted spectra. When the dispersion axis is +divided into more than one sample, the dependence of the dispersion widths +and shifts along the dispersion may be investigated. + +Each spectral sample has a low order continuum subtracted using a +noninteractive iterative rejection algorithm to exclude the spectral +lines. This technique is described further under the topic +\fIcontinuum\fR. The continuum subtracted spectrum is then tapered with a +cosine bell function and autocorrelated. The length of the taper and the +range of shifts for the correlation is set by the \fIcorwidth\fR +parameter. This parameter should be only slightly bigger than the expected +feature widths to prevent correlations between different spectral lines. +The correlation profile is offset to zero at the edges of the profile and +normalized to unity at the profile center. The profiles may be viewed as +described below. + +If there is more than one spatial sample the central spectrum is also +crosscorrelated against the other spectra at the same dispersion +sample. The crosscorrelation is computed in exactly the same way as +the autocorrelation. The crosscorrelation profiles are only used for +determining shifts between the two samples and are not used in the +width determinations. + +A cubic spline interpolator is fit to the profiles and this interpolation +function is used to determined the profile width and center. The width is +measured at a point given by the \fIlevel\fR parameter relative to the +profile peak. It may be specified as a fraction of the peak if it is less +than one or a percentage of the peak if it is greater than one. The +default value of 0.5 selects the full width at half maximum. The +autocorrelation width is divided by the square root of two to yield an +estimate of the width of the spectral features in the spectrum in units of +pixels. + +Having computed the width and shift for each input image at each sample, +the "best focus" values (focus, width, and shift) are estimated for each +sample. As discussed later, it is possible to exclude some samples +from this calculation by deleting them graphically. +First the images with the smallest measured width at each distinct +focus are selected since it is possible to input more than one image at the +same focus. The selected images are sorted by focus value and the image +with the smallest width is found. If that image has the lowest or highest +focus (which will always be the case if there are only one or two images) +then the best focus, width, and shift are those measured for that image. +If there are three or more focus values and the minimum width focus image +is not an endpoint then parabolic interpolation is used to find the minimum +width. The focus at this minimum width is the "best focus". +The dispersion shift is the parabolic interpolation of the shifts at +the best focus. The "average best focus" values are then the average of +the "best focus" values over all samples. + +After computing the correlation profiles, the profile widths and shifts, +and the best focus values, an interactive graphics mode is entered. This +is described in detail below. The graphics mode is exited with the 'q' +key. At this point the results are written to the standard output (usually +the terminal) and to a logfile if one is specified. The output begins with +a banner identifying the task, version of IRAF, the user, and the date and +time. The next line gives the best average focus and width. This banner +also appears in all plots. Then each image is listed with the focus value +and average width (over all samples). Finally the image with the smallest +average width is identified and tables showing the width and shifts (if +computed) at each sample position are printed. If there is only one sample +then the tables are not output. + +INTERACTIVE GRAPHICS MODE + +There are five types of plot formats which are selected with the 'b', 'p', +'s', 'w', and 'z' keys. The available formats and their content are +modified depending on the number of images and the number of samples. If +there is only one image or one sample per image some of the plot formats +are not available. If there are a large number of images or a large number +of samples the content of the plot formats may be abbreviated for +legibility. + +In all plots there is a concept of the current image and the current +sample. In general there is an indication, usually a box, of which image +and sample is the current one. The current image and sample are +changed by pointing at a particular point, box, circle, or symbol for that +image and sample and typing a key. + +The 'b' key produces summary graphs of the best focus values (as described +above) at each sample position. There must be more than one image and more +than one sample (either along or across the dispersion or both). This is +the initial plot shown when this condition is satisfied. The central graph, +which is always drawn, represents the best focus (smallest) width at each +sample by circles of size proportional to the width. The position of the +circle indicates the central line and column of the sample. If there are +multiple samples across the dispersion and the \fIshifts\fR parameter is +set then little vectors are also drawn from the center of the circle in the +direction of the shift and with length proportional to the shift. If there +are 5 or fewer samples in each dimension the values of the best focus and +the width and shift (if computed and nonzero) at that focus, are printed on +the graph next to the circles. If there are more samples this information +may be obtained by pointing at the sample and typing the space key. + +In addition to the spatial graph there may be graphs along the line or column +axes. These graphs again show the widths as circles but one axis is either +the line or column and the other axis is either the best focus value or the +shift. The focus graph marks the best average focus (over all samples) by +a dashed line and a solid line connects the mean focus at each column or +line. The focus graphs will only appear if there is more than one sample +along a particular image axis. The shift graphs will only appear if the +shifts are computed (\fIshifts\fR parameter is yes) and there is more than +one sample along a particular dimension. Lines are drawn at zero shift and +connecting the mean shift at each point along the spatial axis. Note that +there is always a point at zero shift which is the reference sample. + +The best focus graphs are the exception in showing a current image and +sample. When changing to one of the other plots based on a current image +and sample the circle from the central spatial graph nearest the cursor is +used (note that the other focus and shift graphs are ignored). The sample +is defined by it's spatial position and the image is the one with +focus closest to the best focus value of that sample. + +The 'w' key produces a graph showing the sample widths as a function of +focus value. There must be more than one image and more than one sample +for this type of graph. The top graph is a symbol plot of width verses +focus. The symbols are crosses except for the current image which is shown +with pluses. The current sample is highlighted with a box. Also shown is +a long dashed line connecting the widths for the current sample at each +focus value and short dashed lines showing the best average focus and +width. + +The lower portion of the 'w' key are graphs showing the +widths as circles with size proportional to the width and position +corresponding to the spatial position of the sample in the image. If there +are more than 5 samples in either dimension the graph is for the current +image. Otherwise there is a box for each image with the focus value +(provided there are not too many images) indicated. The circles are +arranged as they would be spatially in columns and rows. The samples +closest to the best focus are indicated by pluses. This allows seeing +where the best focus values cluster. The current image and sample are +indicated by highlighting boxes. + +The 'p' key produces graphs of the autocorrelation profiles. This also +requires more than one image and more than one sample. The top graph shows +the profiles of all images at a particular sample and the bottom graph shows +the profiles of all samples at a particular image. The bottom sample boxes +are arranged in columns and rows in the same way the samples are +distributed in the image. The current image and current sample are +highlighted by a box. + +The profiles are drawn with a solid line using the interpolator function +and the actual pixel lags are indicated with pluses. The profiles are +drawn shifted by the amount computed from the crosscorrelation. +Note that the shift is added to the autocorrelation profile +and the crosscorrelation profile is not what is plotted. The zero shift +position is indicated by a vertical line. If there are less than 25 boxes +the boxes are labeled by the width, shift (if nonzero), and focus. + +The 's' key plot is similar to the 'p' key plot but shows the spectra +rather than the profiles. The top graphs are the spectra of each image at +a particular sample and the bottom graphs are the spectra of each sample +for a particular image. The current image and sample are highlighted by a +box. + +The 'z' key graphs the autocorrelation profile and the spectrum +of a single sample. This graph provides scales which are not +provided with the 'p' and 's' graphs. If there is only one image +and one sample then this is the only plot available. + +It is possible to exclude some of the samples from the calculation +of the best focus and best average focus values. This is done by +deleting them using the 'd' key. When using the 'd' key you must +specify the sample to be deleted in one of the graphs. You are +then asked if only that sample (point) is to be deleted, if all +samples from that image are to be deleted, or if the same sample +from all images is to be deleted. The deleted data is no longer +shown explicitly but the space occupied by the data is still present +so that the data may be included again by typing the 'u' undelete +key. When the task is exited with the 'q' key the printed and +logged results will have the deleted data excluded. + +The remaining cursor keys do the following. The '?' key gives a +summary of the cursor keys. The 'r' key redraws the current plot. +The space key prints information about the current sample. This +is mostly used when there are too many images or samples to annotate +the graphs with the focus, width, and shift. Finally the 'q' +key quits the task. +.ih +EXAMPLES +1. A series of 2D focus images is obtained with focus values +starting at 400 in steps of -50. The slit is between columns 50 +and 130. There are 3 samples across the dispersion and 3 along +the dispersion. + +.nf + cl> lpar specfocus + images = "@imlist" List of images + (focus = "400x-50") Focus values + (corwidth = 20) Correlation width + (level = 0.5) Percent or fraction of peak + (shifts = yes) Compute shifts across the disp?\n + (dispaxis = 2) Dispersion axis (long slit only) + (nspectra = 3) Number of spec samples (ls only) + (ndisp = 3) Number of dispersion samples + (slit1 = 50) Lower slit edge + (slit2 = 130) Upper slit edge\n + (logfile = "logfile") Logfile + (mode = "ql") + cl> specfocus @imlist + <Interactive graphics which is exited with the 'q' key> + SPECFOCUS: NOAO/IRAF V2.10EXPORT valdes Thu 19:41:41 17-Sep-92 + Best avg focus at 206.6584 with avg width of 2.91 at 50% of peak + + -- Average Over All Samples + + Image Focus Width + jdv011.imh 100. 3.78 + jdv010.imh 150. 3.28 + jdv009.imh 200. 2.95 + jdv008.imh 250. 3.17 + jdv007.imh 300. 3.41 + jdv006.imh 350. 3.74 + jdv005.imh 400. 4.16 + + -- Image jdv009.imh at Focus 200. -- + + + Width at 50% of Peak: + + Columns + 50-76 77-103 104-130 + Lines +--------------------------------- + 2-267 | 2.93 2.58 2.74 + 268-533 | 3.17 2.76 2.89 + 534-799 | 3.77 2.23 3.50 + + Position Shifts Relative To Central Sample: + + Columns + 50-76 77-103 104-130 + Lines +--------------------------------- + 2-267 | 0.68 0.00 0.18 + 268-533 | 0.64 0.00 0.13 + 534-799 | 0.92 0.00 0.16 +.fi +.ih +SEE ALSO +imexamine, implot, ranges, splot +.endhelp diff --git a/noao/obsutil/src/doc/sptime.hlp b/noao/obsutil/src/doc/sptime.hlp new file mode 100644 index 00000000..a2c0f242 --- /dev/null +++ b/noao/obsutil/src/doc/sptime.hlp @@ -0,0 +1,1218 @@ +.help sptime Nov01 noao.obsutil +.ih +NAME +sptime -- spectroscopic exposure time calculator +.ih +USAGE +sptime +.ih +PARAMETERS +The parameters in this task have certain common features. +.ls (1) +All parameters, except \fIspectrograph\fR and \fIsearch\fR, may be +specified as spectrograph table parameters of the same name. Some +parameters may also be specified in other tables. The tables in which the +paramters may be specified are shown in brackets. Table values are used +only if a string parameter is "" or a numeric parameter is INDEF. +Therefore parameter set values override values in the tables. To override +a table specified in the spectrograph file by no file the special value +"none" is used. This task also uses default values, shown below in +parenthesis, for parameters that have no value specified either in the +parameter set or in a table. +.le +.ls (2) +Parameters that specify a table take the value of a file or a numeric +constant. A constant is like a table with the same values for all value +of the independent variable(s). +.le +.ls (3) +Tables which are specified as filenames are sought first in the current +working directory, then in one of the directories given by the +\fIsearch\fR parameter, and finally in the package library directory +sptimelib$. +.le + + +.ls time = INDEF (INDEF) [spectrograph] +Total exposure time in seconds. This time may be divided into shorter +individual exposure times as defined by the \fImaxexp\fR parameter. If +the value is INDEF then the exposure time needed to achieve the +signal-to-noise per pixel specified by the \fIsn\fR parameter is computed. +.le +.ls sn = 25. (25.) [spectrograph] +Desired signal-to-noise per pixel at the central wavelength if the +exposure \fItime\fR parameter is not specified. +.le + + +The following parameters define the source and sky/atmosphere background +spectra. +.ls spectrum = "blackbody" +Source spectrum. This may be a table or one of the following special words: +.ls blackbody +Blackbody spectrum with temperature given by the \fItemperature\fR +parameter. +.le +.ls flambda_power +Power law in f(lambda) with index given by the \fIindex\fR parameter; +f(lambda) proportional to lambda^(index). +.le +.ls fnu_power +Power law in f(nu) with index given by the \fIindex\fR parameter; +f(nu) proportional to nu^(index). +.le + +The table is a two column text file of wavelength in Angstroms and flux in +ergs/s/cm^2/A. +.le +.ls spectitle = "" [spectrum|spectrograph] +Spectrum title. +.le +.ls E = 0. (0.) [spectrum|spectrograph] +The E(B-V) color excess to apply a reddening to the source spectrum. The +reddening maintains the same table or reference flux at the reference +wavelength. A value of zero corresponds to no reddening. +.le +.ls R = 3.1 (3.1) [spectrum|spectrograph] +The R(V) = A(V)/E(B-V) for the extinction law. The extinction law is that +of Cardelli, Clayton, and Mathis, \fBApJ 345:245\fR, 1989. The default +R(V) is typical of the interstellar medium. +.le +.ls sky = "" ("none") [spectrograph] +Sky or background table. The table is a two or three column text file +consisting of wavelength in Angstroms, optional moon phase between 0 (new +moon) and 14 (full moon), and flux in ergs/s/cm^2/A/arcsec^2. +.le +.ls skytitle = "" [sky|spectrograph] +Sky title. +.le +.ls extinction = "" ("none") [spectrograph] +Extinction table. The table is a two column text file consisting of +wavelength in Angstroms and extinction in magnitudes per airmass. +.le +.ls exttitle = "" [spectrograph] +Extinction title. +.le + + +The following parameters are used with the source spectrum is specified +by the special functions. +.ls refwave = INDEF (INDEF) [spectrum|spectrograph] +Reference wavelength, in units given by the \fIunits\fR parameter, defining +the flux of the source. This is also used as the wavelength where +reddening does not change the spectrum flux. A value of INDEF uses the +observation central wavelength. +.le +.ls refflux = 10. (10.) [spectrograph] +Reference source flux or magnitude at the reference wavelength for the +model spectral distributions. The units are specified by the funits parameter. +.le +.ls funits = "AB" ("AB") [spectrograph] +Flux units for the reference flux. The values are "AB" for monochromatic +magnitude, "F_lambda" for ergs/s/cm^2/A, "F_nu" for ergs/s/cm^2/Hz, +and standard bandpasses of U, B, V, R, I, J, H, Ks, K, L, L' and M. +.le +.ls temperature = 6000. (6000.) [spectrograph] +Blackbody temperature for a blackbody source spectrum in degrees Kelvin. +.le +.ls index = 0. (0.) [spectrograph] +Power law index for the power law source spectrum. +.le + + +The following parameters are observational parameters describing either +the observing conditions or spectrograph setup. +.ls seeing = 1. (1.) [spectrograph] +The full width at half maximum (FWHM) of a point source in arc seconds. +.le +.ls airmass = 1. (1.) [spectrograph] +The airmass of the observation. This is only used if an extinction table +is specified. +.le +.ls phase = 0. (0.) [spectrograph] +The moon phase running from 0 for new moon to 14 for full moon. This is +used if the sky spectrum is given as a function of the moon phase. +.le +.ls thermal = 0. (0.) [telescope|spectrograph] +Temperature in degress Kelvin for the thermal background of the telescope +and spectrograph. If greater than zero a blackbody surface brightness +background is computed and multiplied by an emissivity specified by +the \fIemissivity\fR table. +.le +.ls wave = INDEF (INDEF) [spectrograph] +Central wavelength of observation in units given by the \fIunits\fR +parameter. If the value is INDEF it is determined from the efficiency peak +of the disperser. +.le +.ls order = INDEF (INDEF) [spectrograph] +Order for grating or grism dispersers. If the value is INDEF it is +determined from the order nearest the desired central wavelength. If both +the order and central wavelength are undefined the first order is used. +.le +.ls xorder = INDEF (INDEF) [spectrograph] +Order for grating or grism cross dispersers. If the value is INDEF it +is determined from the order nearest the desired central wavelength. If +both the order and central wavelength are undefined the first order is +used. +.le +.ls width = INDEF (-2.) [aperture|spectrograph] +The aperture width (dispersion direction) for rectangular apertures +such as slits. Values may be positive to specify in arc seconds or +negative to specify in projected pixels on the detector. +.le +.ls length = INDEF (-100.) [aperture|spectrograph] +The aperture length (cross dispersion direction) for rectangular +apertures such as slits. Values may be positive to specify in arc seconds +or negative to specify in projected pixels on the detector. +.le +.ls diameter = INDEF (-2.) [fiber|aperture|spectrograph] +The aperture diameter for circular apertures. Values +may be positive to specify in arc seconds or negative to specify in +projected pixels on the detector. If it is found in the fiber table, +positive values are treated as mm at the focal plane instead of arc seconds. +.le +.ls xbin = 1 (1) [detector|spectrograph] +Detector binning along the dispersion direction. +.le +.ls ybin = 1 (1) [detector|spectrograph] +Detector binning along the spatial direction. +.le + + +The following parameters a miscellaneous parameters for the task. +.ls search = "spectimedb$" +List of directories to search for the various table files. The current +direction is always searched first and the directory sptimelib$ is searched +last so it is not necessary to include these directories. The list may be +a comma delimited list of directories, an @file, or a template. +.le +.ls minexp = 0.01 (0.01) [spectrograph] +Minimumm time in seconds per individual exposure time. This only applies +when \fItime\fR is INDEF. Adjustment of the exposure time for saturation +will not allow the exposure time to fall below this value. +.le +.ls maxexp = 3600. (3600.) [spectrograph] +Maximum time in seconds per individual exposure. The minimum exposure time +has precedence over this value. If the total exposure time exceeds this +amount by more than 1% then the total exposure time will be divided up into +the fewest individual exposures with equal exposure time that are less than +this amount. Note that by making the minimum and maximum times the same a +fixed integration time can be defined. +.le +.ls units = "Angstroms" ("Angstroms") [spectrograph] +Dispersion units for input and output dispersion coordinates. The +units syntax is described in the UNITS section. The most common units +are "Angstroms", "nm", "micron", and "wn". Note that this does not +apply to the dispersion units in the tables which are always in Angstroms. +.le +.ls skysub = "" (default based on context) [spectrograph] +Type of sky and background subtraction. The values are "none" for no +background subtraction, "longslit" for subtraction using pixels in the +aperture, "multiap" for background determined from a number of other +apertures, and "shuffle" for shuffled observations. The multiap case is +typical for fiber spectrographs. For shuffle the duty cycle is 50% and the +exposure times are the sum of both sky and object. If no sky or thermal +background is specified then the default is "none". If a fiber table or +circular aperture is specified the default is "multiap" otherwise the +default is "longslit". +.le +.ls nskyaps = 10 (10) [spectrograph] +Number of sky apertures when using "multiap" sky subtraction. +.le +.ls subpixels = 1 (1) [spectrograph] +Number of subpixels within each computed pixel. +The dispersion pixel width is divided into this number of equal +width subpixels. The flux at the dispersions represented by the subpixels +are computed and then summed to form the full pixel flux. This option is used +when there is structure in the tables, such as the sky and filter tables to +simulate instrumental masking of sky lines, which is finer than a pixel +dispersion width. +.le +.ls sensfunc = "" [spectrograph] +Sensitivity function table. This is a two column text file consisting +of wavelength in Angstroms and sensitivity defined as +2.5*(log(countrate)-log(flambda)), +where countrate is the count rate (without extinction) in counts/s/A +and flambda is the source flux in ergs/s/cm^2/A. This table is used +to compute an efficiency correction given a measurement of the +sensitivity function from standard stars for the instrument. +.le + + +The following parameters control the output of the task. The task +always prints a result page at the central wavelength but additional +graphical and text output may be produced at a set of equally spaced +points across the size of the detector. +.ls output = "object" ("") [spectrograph] +List of quantities to output as graphs and/or in a text file. These are +given as a function of dispersion (as specified by units parameters) +sampled across the dispersion coverage of the detector. The choices are: +.ls counts +Object and background counts per individual exposure. +.le +.ls snr +Signal-to-noise ratio per pixel per individual exposure. +.le +.ls object +Object counts per individual exposure. This includes contribution +from other orders if there is no cross dispersion and the blocking +filters do not completely exclude other orders. +.le +.ls rate +Photons/second/A per individual exposure for the object and background. +.le +.ls atmosphere +Percent transmission of the atmosphere. +.le +.ls telescope +Percent transmission of the telescope. +.le +.ls adc +Percent transmission of the ADC if one is used. +.le +.ls aperture +Percent transmission of the aperture. +.le +.ls fiber +Percent transmission of the fiber if one is used. +.le +.ls filter +Percent transmission of the first filter if one is used. +.le +.ls filter2 +Percent transmission of the second filter if one is used. +.le +.ls collimator +Percent transmission of the collimator. +.le +.ls disperser +Percent efficiency of the disperser. +.le +.ls xdisperser +Percent efficiency of the cross disperser if one is used. +.le +.ls corrector +Percent transmission of the corrector if one is used. +.le +.ls camera +Percent transmission of the camera. +.le +.ls detector +Percent DQE of the detector. +.le +.ls spectrograph +Percent transmission of the spectrograph if a transmission +function is defined. +.le +.ls emissivity +Emissivity of the telescope/spectrograph if an emissivity function +is defined. +.le +.ls thruput +Percent system thruput from telescope to detected photons. +.le +.ls sensfunc +Sensitivity function values given as 2.5*(log(countrate)-log(flambda)), +where countrate is the count rate (without extinction) in counts/s/A +and flambda is the source flux in ergs/s/cm^2/A. +.le +.ls correction +Multiplicative correction factor needed to convert the computed +count rate to that given by an input sensitivity function. +.le +.ls ALL +All of the above. +.le +.le +.ls nw = 101 (101) [spectrograph] +Number of dispersion points to use in the output graphs and text +file. Note that this is generally less than the number of pixels in +the detector for execution speed. +.le +.ls list = "" [spectrograph] +Filename for list output of the selected quantities. The output +will be appended if the file already exists. +.le +.ls graphics = "stdgraph" ("stdgraph") [spectrograph] +Graphics output device for graphs of the output quantities. +.le +.ls interactive = "yes" ("yes") [spectrograph] +Interactive pause after each graph? If "yes" then cursor input is +enabled after each graph otherwise all the graphs will be drawn without +pause. When viewing the graphs interactively this should be "yes" otherwise +the graphs will flash by rapidly leaving the last graph on the screen. +When outputing only one graph or when redirecting the graphs to a +printer or file then setting this parameter to "no" is suggested. +.le + +The last parameter is a "parameter set" ("pset") containing all the +spectrograph parameters. +.ls specpars = "" +Spectrograph parameter set. If "" then the default pset \fBspecpars\fR +is used otherwise the named pset is used. +.le + + + +SPECPARS PARAMETERS +.ls spectrograph = "" +Spectrograph efficiency table. This text file may contain parameters and an +efficiency table. The table consists of two columns containing +wavelengths and efficiencies. The efficiencies are for all elements +which are not accounted for by other tables. +.le +.ls title = "" [spectrograph] +Title for the spectrograph. +.le +.ls apmagdisp = INDEF (1.), apmagxdisp = INDEF (1.) [spectrograph] +Magnification between the entrance aperture and the detector along and +across the dispersion direction. This describes any magnification (or +demagnification) in the spectrograph other than that produced by the ratio +of the collimator and camera focal lengths and anamorphic magnification +from the disperser. The may consist of actual magnification optics or +projection effects such as tilted aperture plates (when the aperture size +is specified in the untilted plate). +.le +.ls inoutangle = INDEF (INDEF) [spectrograph] +Incident to diffracted grating angle in degrees for grating dispersers. +For typical spectrographs which are not cross dispersed this is the +collimator to camera angle. If the value is INDEF derived from the grating +parameters. +.le +.ls xinoutangle = INDEF (INDEF) [spectrograph] +Incident to diffracted grating angle in degrees for grating cross +dispersers. If the value is INDEF it is derived from the grating +parameters. +.le + + +.ls telescope = "" [spectrograph] +Telescope efficiency table as a function of wavelength. +.le +.ls teltitle = "" [telescope|spectrograph] +Telescope title. +.le +.ls area = INDEF (1.) [telescope|spectrograph] +Effective collecting area of the telescope in m^2. The effective area +includes reductions in the primary area due to obstructions. +.le +.ls scale = INDEF (10.) [telescope|spectrograph] +Telescope plate scale, in arcsec/mm, at the entrance aperture of the +spectrograph. +.le +.ls emissivity = "" [telescope|spectrograph] +Emissivity table. The emissivity is for all elements in the telescope +and spectrograph. If an emissivity is specified and an the \fIthermal\fR +temperature parameter is greater than zero then a thermal background +is added to the calculation. +.le +.ls emistitle = "" [emissivity|spectrograph] +Title for the emissivity table used. +.le + + +.ls corrector = "" [spectrograph] +Efficiency table for one or more correctors. +.le +.ls cortitle = "" [corrector|spectrograph] +Title for corrector table used. +.le +.ls adc = "" [spectrograph] +Efficiency table for atmospheric dispersion compensator. +.le +.ls adctitle = "" [adc|spectrograph] +Title for ADC table used. +.le + + +.ls disperser = "" [spectrograph] +Disperser table. If this file contains an efficiency table it applies +only to first order. An alternate first order table and tables for +other orders are given by table parameters "effN", where N is the order. +.le +.ls disptitle = "" [disperser|spectrograph] +Title for disperser. +.le +.ls disptype = "" ("grating") [disperser|spectrograph] +Type of disperser element. The chocies are "grating", "grism", or "generic". +The generic setting will simply use the desired central wavelength and +dispersion without a grating or grism model. One effect of this is that +the mapping between detector pixel and wavelength is linear; i.e. a constant +dispersion per pixel. +.le +.ls gmm = INDEF (300.) [disperser|spectrograph] +Ruling in lines per mm. If not specified it will be derived from the +other disperser parameters. If there is not enough information to +derive the ruling then an ultimate default of 300 lines/mm is used. +.le +.ls blaze = INDEF (6.) [disperser|spectrograph] +Blaze (grating) or prism (grism) angle in degrees. If not specified it +will be derived from the other disperser parameters. If there is not +enough information to derive the angle then an ultimate default of 6 +degrees is used. +.le +.ls oref = INDEF (1) [disperser|spectrograph] +When a central (blaze) wavelength is specified this parameter indicates +which order it is for. +.le +.ls wavelength = INDEF (INDEF) [disperser|spectrograph] +Central (blaze) wavelength in Angstroms for the reference order. This +parameter only applies to gratings. If it is not specified it will +be derived from the other disperser parameters. +.le +.ls dispersion = INDEF (INDEF) [disperser|spectrograph] +Central dispersion in A/mm for the reference order. This parameter only +applies to gratings. If it is not specified it will be derived from the +other disperser parameters. +.le +.ls indexref = INDEF (INDEF) [disperser|spectrograph] +Grism index of refraction for the reference order. This parameter only +applies to grisms. If it is not specified it will be derived from +the other disperser parameters. +.le +.ls eff = INDEF (1.) [disperser|spectrograph] +Peak efficiency for the theoretical disperser efficiency function. +When an efficiency table is not specified then a theoretical efficiency +is computed for the disperser. This theoretical efficiency is scaled +to peak efficiency given by this parameter. +.le + + +.ls xdisperser = "" [spectrograph] +Crossdisperser table. If this file contains an efficiency table it applies +only to first order. An alternate first order table and tables for +other orders are given by table parameters "xeffN", where N is the order. +.le +.ls xdisptitle = "" [xdisperser|spectrograph] +Title for crossdisperser. +.le +.ls disptype = "" ("grating") [xdisperser|spectrograph] +Type of crossdisperser element. The chocies are "", "grating", "grism", +or "generic". The empty string eliminates use of a cross disperser. +The generic setting will simply use the desired central wavelength and +dispersion without a grating or grism model. One effect of this is that +the mapping between detector pixel and wavelength is linear; i.e. a constant +dispersion per pixel. +.le +.ls gmm = INDEF (INDEF) [xdisperser|spectrograph] +Ruling in lines per mm. If not specified it will be derived from the +other crossdisperser parameters. +.le +.ls xblaze = INDEF (6.) [xdisperser|spectrograph] +Blaze (grating) or prism (grism) angle in degrees. If not specified it +will be derived from the other crossdisperser parameters. +.le +.ls xoref = INDEF (1) [xdisperser|spectrograph] +When a central (blaze) wavelength is specified this parameter indicates +which order it is for. +.le +.ls xwavelength = INDEF (INDEF) [xdisperser|spectrograph] +Central (blaze) wavelength in Angstroms for the reference order. This +parameter only applies to gratings. If it is not specified it will +be derived from the other crossdisperser parameters. +.le +.ls xdispersion = INDEF (INDEF) [xdisperser|spectrograph] +Central dispersion in A/mm for the reference order. This parameter only +applies to gratings. If it is not specified it will be derived from the +other crossdisperser parameters. +.le +.ls xindexref = INDEF (INDEF) [xdisperser|spectrograph] +Grism index of refraction for the reference order. This parameter only +applies to grisms. If it is not specified it will be derived from +the other crossdisperser parameters. +.le +.ls xeff = INDEF (1.) [xdisperser|spectrograph] +Peak efficiency for the theoretical crossdisperser efficiency function. +When an efficiency table is not specified then a theoretical efficiency +is computed for the crossdisperser. This theoretical efficiency is scaled +to peak efficiency given by this parameter. +.le + + +.ls aperture = "" (default based on context) [spectrograph] +Aperture table. The text file gives aperture thruput as a function of the +aperture size in units of seeing FWHM. For rectangular apertures there are +two independent variables corresponding to the width and length while for +circular apertures there is one independent variable corresponding to the +diameter. If not specified a default table is supplied. If a fiber table +or a diameter is specified then the table "circle" is used otherwise the +table "slit" is used. Because "sptimelib$" is the last directory searched +there are default files with these names in this directory for Gaussian +seeing profiles passing through a circular or slit aperture. +.le +.ls aptitle = "" [aperture|spectrograph] +Title for aperture used. +.le +.ls aptype = "" (default based on context) [aperture|spectrograph] +The aperture types are "rectangular" or "circular". If the +parameter is not specified then if the aperture table has two columns the +type is "circular" otherwise it is "rectangular". +.le + + +.ls fiber = "" [spectrograph] +Fiber transmission table. The transmission is a function of wavelength +in Angstroms. If no fiber transmission is specified then no fiber +component is included. +.le +.ls fibtitle = "" [fiber|spectrograph] +Title for fiber transmission used. +.le + + +.ls filter = "" [spectrograph] +Filter transmission table. The transmission is a function of wavelength +in Angstroms. If no filter transmission is specified then no filter +component is included. +.le +.ls ftitle = "" [filter|spectrograph] +Title for filter transmission used. +.le +.ls filter2 = "" [spectrograph] +Filter transmission table. The transmission is a function of wavelength +in Angstroms. If no filter transmission is specified then no filter +component is included. +.le +.ls f2title = "" [filter|spectrograph] +Title for filter transmission used. +.le +.ls block = "" ("no") [filter|spectrograph] +If "yes" then no check will be made for other orders. +.le + + +.ls collimator = "" (1.) [spectrograph] +Collimator transmission table. The transmission is a function of +wavelength in Angstroms. If no collimator is specified then a unit +transmission is used. +.le +.ls coltitle = "" [collimator|spectrograph] +Title for collimator. +.le +.ls colfl = INDEF (1.) [collimator|spectrograph] +Collimator focal length in meters. The ratio of the collimator to camera +focal lengths determines the magnification between the aperture and the +detector. +.le + +.ls camera = "" (1.) [spectrograph] +Camera transmission table. The transmission is a function of wavelength +in Angstroms. If no camera is specified then a unit transmission +is used. +.le +.ls camtitle = "" [camera|spectrograph] +Title for camera. +.le +.ls camfl = "" (1.) [camera|spectrograph] +Camera focal length in meters. The ratio of the collimator to +camera focal lengths determines the magnification between the aperture +and the detector. The camera focal length also determines the dispersion +scale at the detector. +.le +.ls resolution = "" (2 pixels) [camera|spectrograph] +Camera resolution on the detector in mm. +.le +.ls vignetting = "" (1.) [camera|spectrograph] +Vignetting table. The independent variable is distance from the center +of the detector in mm. The value is the fraction the light transmitted. +If no vignetting table is specified then no vignetting effect is applied. +.le + + +.ls detector = "" (1.) [spectrograph] +Detector DQE table. The DQE is a function of wavelength in Angstroms. +.le +.ls dettitle = "" [detector|spectrograph] +Title for detector. +.le +.ls ndisp = INDEF (2048) [detector|spectrograph] +Number of pixels along the dispersion. +.le +.ls pixsize = INDEF (0.02) [detector|spectrograph] +Pixel size (assumed square) in mm. +.le +.ls gain = INDEF (1.) [detector|spectrograph] +The conversion between photons and detector data numbers or counts. +This is given as photons/ADU where ADU is analog-to-digital unit. +.le +.ls rdnoise = INDEF (0.) [detector|spectrograph] +Readout noise in photons. +.le +.ls dark = INDEF (0.) [detector|spectrograph] +Dark count rate in photons/s. +.le +.ls saturation = INDEF [detector|spectrograph] +Number of detected photons in a pixel resulting in saturation. +The default is no saturation. The time per exposure will be reduced, +but no lower than the minimum time per exposure, +and the number of exposures increased to try and avoid saturation. +.le +.ls dnmax = INDEF [detector|spectrograph] +Maximum data number or ADU allowed. The default is no maximum. +The time per exposure will be reduced, +but no lower than the minimum time per exposure, +and the number of exposures increased to try and avoid overflow. +.le +.ls xbin = 1 (1) [detector|spectrograph] +Detector binning along the dispersion direction. +.le +.ls ybin = 1 (1) [detector|spectrograph] +Detector binning along the spatial direction. +.le +.ih +DISCUSSION + + +OVERVIEW + +The spectroscopic exposure time package, \fBSPECTIME\fR, consists of a +general calculation engine, \fBSPTIME\fR, and a collection of user or +database defined IRAF scripts. The scripts are one type of user interface +for \fBSPTIME\fR. Other user interfaces are Web-based forms and IRAF +graphics/window applications. The user interfaces customize the general +engine to specific spectrographs by hiding components and parameters not +applicable to that spectrograph and guiding the user, through menus or +other facilities, in the choice of filters, gratings, etc. However, +\fBSPTIME\fR is a standard IRAF task that can be executed directly. + +\fBSPTIME\fR takes an input source spectrum (either a reference blackbody, +a power law, or a user spectrum), a background "sky" spectrum and a +instrumental thermal background, reddening to apply to the spectrum, +observing parameters such as exposure time, central wavelength, seeing, +airmass, and moon phase, instrument parameters such as aperture sizes and +detector binning, a description of the spectrograph, and produces +information about the expected signal and signal-to-noise ratio in the +extracted one-dimensional spectrum. The output consists of a description +of the observation, signal-to-noise statistics, and optional graphs and +tables of various quantities as a function of wavelength over the +spectrograph wavelength coverage. + +\fBSPTIME\fR models a spectroscopic system as a flow of photons from a +source to the detector through various optical components. Background +photons from the sky, atmosphere, and the thermal emission from the +telescope and spectrograph are added. It then computes signal-to-noise +ratios from the detected photons of the source and background and the +instrumental noise characteristics. The spectroscopic system components +are defined at a moderate level of detail. It is not so detailed that +every optical element has to be described and modeled and not so coarse +that a single throughput function is used (though one is free to put all +the thruput information into one component). Not all components modeled by +the task occur in all spectroscopic systems. Therefore many of the +components can be left out of the calculation. + +The components currently included in \fBSPTIME\fR are: + +.nf + - the atmosphere (extinction and IR transmission) + - the telescope (all elements considered as a unit) + - an optional atmospheric dispersion compensator + - the entrance aperture (slits, fibers, masks, etc.) + - an optional fiber feed + - a spectrograph (for components not represented elsewhere) + - filters + - a collimator + - a disperser (grating, grism, prism, etc) + - a optional cross disperser (grating, grism, prism, etc) + - a corrector (either in the telescope of spectrograph) + - a camera + - a detector +.fi + +Each of these components represent a transmission function specifying the +fraction of incident light transmitted or detected as a function of some +parameter or parameters. Except for the aperture, which is a function of +the incident source profile (typically the seeing profile) relative to the +aperture size, the transmissions of the components listed above are all +functions of wavelength. + +All the component transmission functions may be specified as either numeric +values or as tables. A numeric value is considered to be a special type of +table which has the same value at all values of the independent parameters. +By specifying only numeric values the task may be run without any table +files. To obtain information at a single wavelength this is all that is +needed. + +To specify a dependence on wavelength or other parameter a text file table +with two or more columns may be specified. The tables are interpolated in +the parameter columns to find the desired value in the last column. The +tables are searched for in the current directory and then in a list of user +specified directories. Thus, users may place files in their work area to +override system supplied files and observatories can organize the data +files in a database directory tree. + +In addition to transmission or DQE functions the spectrograph is described +by various parameters. All the parameters are described in the PARAMETERS +section. For flexibility parameters may be defined either in the +parameter set or in one or more table files. In all cases the parameter +set values have precedence. But if the values are "" for string parameters +or INDEF for numeric parameters the values are found either in the +spectrograph table or in a table that is associated with the parameter. + +Therefore table files provide for interchangeable components, each with +their own transmission curves, and for organizing parameters for different +instruments. Note that a table file may contain only parameters, only +a table, or both. + +There is also another way to maintain a separate file for different +instruments. The \fIspecpars\fR parameter is a "parameter set" or "pset". +The default value of "" corresponds to the pset task \fBspecpars\fR. +However, using \fBeparam\fR one can edit this pset and then save the +parameters to a named parameter file with ":e <name>.par". This +pset can be edited with \fBeparam\fR and specified in the +\fIspecpars\fR parameter. One other point about pset parameters is that +they can also be included as command line arguments just as any other +parameter in the main task parameters. + +Many spectrographs provide a wide variety of wavelength regions and +dispersions. For gratings (and to some extent for grisms) this means use +of different gratings, orders, tilts, and possibly camera angles in the +spectrograph. The transmission as a function of wavelength (the grating +efficiency) changes with these different setups. If the transmission +function is given as an interpolation table this would require data files +for each setup of each disperser. The structure of \fBSPTIME\fR allows +for this. + +However, it is also possible to specify the grating and spectrograph +parameters and have the task predict the grating efficiency in any +particular setup. In many cases it may be easier to use the calculated +efficiencies rather than measure them. Depending on the level of accuracy +desired this may be adequate or deviations from the analytic blaze function +can be accounted for in another component. + + +TABLES + +\fBSPTIME\fR uses text files to provide parameters and interpolation +tables. The files may contain comments, parameters, and tables. + +Comment lines begin with '#' and may contain any text. They can occur +anywhere in the file, though normally they are at the beginning of the file. + +Parameters are comment lines of the form + +.nf + # [parameter] = [value] +.fi + +where whitespace is required between each field, [parameter] is a single +word parameter name, and [value] is a single word value. A quoted string +is a single word so if the value field contains whitespace, such as in +titles, it must be quoted. Any text following the value is ignored and may +be used for units (not read or used by the program) or comments. + +The parameters are those described in the PARAMETERS section. The tables +in which the parameters may be included are identified in that section +in the square brackets. Note that it is generally true that any parameter +may appear in the spectrograph table. + +The table data is a multicolumn list of numeric values. The list must be +in increasing order in the independent columns. Only 1D (two columns) and +2D (three columns) tables are currently supported. 2D tables must form a +regular grid. This means that any particular value from column one must +occur for all values of column 2 and vice versa. The table is +interpolated as needed. The interpolation is linear or bi-linear. +Extrapolation outside of the table consists of the taking the nearest +value; thus, a single line may be used to define a constant value for all +values of the independent variable(s). + +Normally the table values, the dependent variable in the last column, are +in fractional transmission or DQE. There is a special parameter, +"tablescale", which may be specified to multiply the dependent variable +column. This would mainly be used to provide tables in percent rather +than fraction. + +The independent variable columns depend on the type of table. Most tables +are a function of wavelength. Currently wavelengths must be in Angstroms. + +The types of tables and the units of the columns are listed below. + +.nf + spectrum - Angstroms ergs/s/cm^2/A + sky - Angstroms ergs/s/cm^2/A/arcsec^2 + extinction - Angstroms mag/airmass + spectrograph - Angstroms transmission + telescope - Angstroms transmission + emissivity - Angstroms emissivity + adc - Angstroms transmission + fiber - Angstroms transmission + collimator - Angstroms transmission + filter - Angstroms transmission + disperser - Angstroms transmission + xdisperser - Angstroms transmission + corrector - Angstroms transmission + camera - Angstroms transmission + detector - Angstroms transmission + sensitivity - Angstroms 2.5*(log(countrate)-log(flambda)), + + sky - Angstroms moonphase ergs/s/cm^2/A/arcsec^2 + aperture - diameter/FWHM transmission + aperture - width/FWHM length/FWHM transmission + vignetting - mm transmission +.fi + +The disperser and crossdisperser files have an additional feature to allow +for efficiency curves at different orders. The parameter "effN" (or "xeffN +for crossdispersers), where N is the order, may be specified whose value is +a separate table (or constant). If there is no "eff1/xeff1" (efficiency in +first order) then any efficiency table in the disperser table is used. In +other words, any table in the disperser file applies only to first order +and only if there is no "eff1/xeff1" parameter defining a separate first +order efficiency file. + +DISPERSION UNITS + +The output results, text file, and graphs are presented in dispersion +units defined by the \fIunits\fR parameter. In addition the \fIwave\fR +and \fIrefwave\fR input parameters are specified in the selected units. +All other dispersion values must currently be specified in Angstroms. + +The dispersion units are specified by strings having a unit type from the +list below along with the possible preceding modifiers, "inverse", to +select the inverse of the unit and "log" to select logarithmic units. For +example "log angstroms" to select the logarithm of wavelength in Angstroms +and "inv microns" to select inverse microns. The various identifiers may +be abbreviated as words but the syntax is not sophisticated enough to +recognize standard scientific abbreviations except for those given +explicitly below. + +.nf + angstroms - Wavelength in Angstroms + nanometers - Wavelength in nanometers + millimicrons - Wavelength in millimicrons + microns - Wavelength in microns + millimeters - Wavelength in millimeters + centimeter - Wavelength in centimeters + meters - Wavelength in meters + hertz - Frequency in hertz (cycles per second) + kilohertz - Frequency in kilohertz + megahertz - Frequency in megahertz + gigahertz - Frequency in gigahertz + m/s - Velocity in meters per second + km/s - Velocity in kilometers per second + ev - Energy in electron volts + kev - Energy in kilo electron volts + mev - Energy in mega electron volts + + nm - Wavelength in nanometers + mm - Wavelength in millimeters + cm - Wavelength in centimeters + m - Wavelength in meters + Hz - Frequency in hertz (cycles per second) + KHz - Frequency in kilohertz + MHz - Frequency in megahertz + GHz - Frequency in gigahertz + wn - Wave number (inverse centimeters) +.fi + +The velocity units require a trailing value and unit defining the +velocity zero point. For example to transform to velocity relative to +a wavelength of 1 micron the unit string would be: + +.nf + km/s 1 micron +.fi + + +CALCULATIONS + +This section describes the calculations, and assumptions behind the +calculations, performed by \fBSPTIME\fR. These include the dispersion and +efficiencies of gratings and grisms, the dispersion resolution, the spatial +resolution and how it applies to the number of object and sky pixels in the +apertures, the object and sky detected photons/counts, the signal-to-noise +ratio , and the exposure time for a given S/N. + + +Gratings + +Gratings are assumed to tilted only around the axis parallel to the +groves and with the incident angle greater than the blaze angle. The +grating equation is then + +.nf + g * m * w = sin(tilt+phi/2) + sin(beta) +.fi + +where g is the number of groves per wavelength unit, m is the order, w is +the wavelength, tilt is the grating tilt measured from the grating normal, +phi is the angle between the incident and diffracted rays, and beta is the +diffracted angle. Phi is a spectrograph parameter and g is a grating +parameter. At the desired central wavelength beta is tilt-phi/2 and at the +blaze peak it is 2*blaze-tilt-phi/2 where blaze is the blaze angle. + +The tilt is computed from the desired central wavelength. It is +also used to compute the grating magnification + +.nf + magnification = cos(tilt-phi/2) / cos(tilt+phi/2) +.fi + +which is used in calculating the projected slit size at the detector. +This number is less than zero so the aperture is actually demagnified. + +The dispersion, treated as constant over the spectrum for the sake of +simplicity, is given by the derivative of the grating equation at +the blaze peak, + +.nf + dispersion = cos(blaze-phi/2) / (g * m * f) +.fi + +where f is the camera focal length. + +The grating efficiency or blaze function is computed as described by +Schroeder and Hilliard (Applied Optics, vol 19, 1980, p. 2833). The +requirements on the grating noted previously correspond to their case A. +As they show, use of incident angles less than the blaze angle, their case +B, significantly degrades the efficiency due to back reflection which is +why this case is not included. The efficiency formulation includes +variation in the peak efficiency due light diffracted into other orders, +shadowing of the groves, and a reflectance parameter. The reflectance +parameter is basically the blaze peak normalization and does not currently +include a wavelength dependence. Thus the peak efficiency is near the +reflectance value but somewhat lower and is order dependent due to the other +effects. + + +Grisms + +Grisms are assumed to have a prism angle equal to the blaze angle of +the inscribed grating. The index of refraction is treated as constant +over the wavelength range of an order, though different index of refraction +values can be specified for each order. + +The grism formula used is a variation on the grating equation. + +.nf + g * m * w = n * sin (theta+prism) - sin (beta+prism) +.fi + +where n is the index of refraction, prism is the prism or blaze angle, +theta is the incident angle relative to the prism face, and beta is the +refracted angle relative to the prism face. Theta and beta are defined so +that at the undeviated wavelength they are zero. In other words at the +undeviated wavelength the light path is a straight through transmission. + +The efficiency is also computed in an analogous manner to the +reflection grating except that shadowing is not included (a consequence of +the blaze face being parallel to the prism face and theta being near +zero). Instead of a reflectance value normalizing the blaze function a +transmission value is used. + + +Scales and Sizes + +The scale between arc seconds on the sky and millimeters at the +aperture(s) of the spectrograph is specified by the \fIscale\fR parameter. +This parameter is used to convert aperture sizes between arc seconds and +millimeters. + +The aperture sizes are magnified or demagnified by three possible factors. +The basic magnification is given by the ratio of the collimator focal +length to the camera focal length. This magnification applies both along +and across the dispersion. + +The camera focal length also determines the dispersion scale on the detector. +It converts radians of dispersion to mm at the detector. + +For grating dispersers there is a demagnification along the dispersion +due to the tilt of the grating(s). The demagnification is computed (as +given previously) from the grating parameters and the spectrograph +parameter giving the angle between the incident and diffracted rays at the +detector center. + +The last magnification factor is given by the spectrograph parameters +"apmagdisp" and apxmagdisp". These define magnifications of the aperture +along and across the dispersion apart from the other two magnifications. +These parameters are often missing which means no additional +magnifications. + +One use for the last magnification parameters is to correct aperture +sizes given as millimeters or arc seconds on a plane tilted with respect to +the focal plane. Such tilted apertures occur with aperture mechanisms +(usually slits) that reflect light for acquisition and guiding. Note that +one only needs to use these terms if users are expected to define the +apertures sizes on the tilted plane. If instead the projection factors are +handled by the spectrograph system and users specify aperture size as +millimeters or arc seconds on the sky then these terms are not needed. + +The above scale factors map arc seconds on the sky and aperture sizes +in millimeter to arc seconds and millimeters projected on the detector. To +convert to pixels on the detector requires the pixel size. +One option in \fBSPTIME\fR is to specify aperture +sizes as projected pixels on the detector (either in the user parameters or +in the aperture description file). Using the detector pixel size and the +scale factors allows conversion of aperture sizes specified in this way +back to the actual aperture size. + + +Resolution + +A camera resolution parameter may be set in the camera description. If +a resolution value is not given it is taken to be 2 pixels. This parameter +is used to define the dispersion resolution element and the number of +pixels across the dispersion imaged by the detector for the aperture and +the object. The latter usage is discussed in the next section. + +The dispersion resolution element, in pixels, is given by + +.nf + | 2 pixels + disp resolution = maximum of | camera resolution + | 1 + min (seeing, apsize) +.fi + +where seeing is the FWHM seeing diameter in pixels and apsize is the +aperture size in pixels. For circular apertures the aperture size is +the diameter and for rectangular apertures it is the width. The first term +comes from sampling considerations, the second from the camera resolution, +and the third from the finite resolution of a pixel (the factor of 1) and +the spread of wavelengths across the aperture or seeing disk. The +dispersion resolution is printed for information and the S/N per dispersion +resolution element is given in addition to the per pixel value. + + +Object and Sky Pixels Across the Dispersion + +The number of pixels across the dispersion in the object and the sky +are required to compute the S/N statistics. The number of pixels +in the projected aperture image is taken to be + +.nf + | diameter + resolution (circular apertures) + aperture pixels = | + | length + resolution (rectangular apertures) +.fi + +where resolution is the camera resolution discussed previously. The value +is rounded up to an integer. + +Objects are assumed to fill circular (fiber) apertures. Therefore the +number of object pixels is the same as the number of pixels in the +aperture. In rectangular (slit) apertures the number of object pixels is +taken to be + +.nf + | 3*seeing + resolution + object pixels = minimum of | + | number of aperture pixels +.fi + +where seeing is the FWHM seeing diameter converted to pixels. The values +are rounded up to an integer. + +The number of sky pixels depends on the type of sky subtraction. +For "longslit" sky subtraction the number of sky pixels is given +by the difference of the number of aperture pixels and the number of +object pixels. For circular apertures this always comes out to zero so +it does not make sense to use longslit sky subtraction. For rectangular +apertures the number of sky pixels in the aperture depends on the +aperture size and the seeing. If the number of sky pixels comes out to +zero a warning is printed. + +For "multiap" sky subtraction the number of sky pixels is the +number of sky apertures times the number of pixels per aperture. + + +Source Counts + +The source spectrum flux at each wavelength, either given in a spectrum +table or as a model distribution, is in units of +photons per second per Angstrom per square centimeter. This is multiplied +by the telescope effective area, the exposure time, and the pixel size in +Angstroms to give the source photons per dispersion pixel per exposure. +This is then multiplied by any of the following terms that apply to arrive +at the number of source photons detected over all spatial pixels. The +spatial integration is implicit in the aperture function. + +.nf + - the extinction using the specified airmass + - the telescope transmission + - the ADC transmission + - the aperture transmission based on the aperture size relative + to the seeing + - the fiber transmission + - the filter transmission (one or two filters) + - the collimator transmission + - the disperser efficiency (one or two dispersers) + - the corrector transmission + - the camera transmission + - the detector DQE +.fi + + +Background Counts + +The sky or atmospheric background spectrum, if one is given, defines a +photon flux per square arc second. When it is given as a function of the +moon phase it is interpolated to the specified moon phase. In addition +if a thermal temperature and an emissivity are given then a thermal +background is computed and added to the sky/atmospheric background. + +The surface brightness of the background is multiplied by the area of the +aperture occupied by the object (in arc seconds) and divided by the +aperture transmission of the source. This is the quantity reported in the +output for the sky photon flux. It is comparable to the source photon +flux. + +Next this flux is multiplied by the telescope effective area, the +exposure time, and the pixel size in Angstroms. Finally it is multiplied +by the same transmission terms as the object except for the extinction. +Note that this removes the aperture transmission term included earlier +giving the background photons as the number passing through the aperture per +object profile. The final value is the number of background photons from the +object. To get the background photons per spatial pixel the value is divided by +the number of spatial pixels occupied by the source. + +If no background subtraction is specified then the background counts are added +to the source counts to define the final source counts and the background +counts are set to zero. + + +Signal-to-Noise Ratio + +The noise attributed to the source and background is based on Poisson +statistics; namely the noise is the square root of the number of photons. +The detector noise is given by a dark count component and a readout noise +component. The noise from the dark counts is obtain by multiplying the +dark count rate by the exposure time and the number of spatial pixels used +in extracting the source and taking the square root. The readout noise is +the detector readout noise parameter multiplied by the square root of the +number of spatial source pixels. + +If background subtraction is selected and the number of available +background pixels is greater than zero then the uncertainty in the +background estimation is computed. The uncertainty in a single pixel is +the square root of the background photons per pixel, the dark counts per +pixel, and the readout noise per pixel. This is divided by the square root +of the number of background pixels to get the uncertainty in the background +estimation for subtraction from the source. + +The total noise is the combination of the source, background, dark count, +and readout noise values and the background subtraction uncertainty added +in quadrature. + +The signal-to-noise ratio per pixel per exposure is the source counts +divided by total noise. This value is multiplied by the square root of +number of pixels per resolution element to get the S/N per resolution +element. If multiple exposures are used to make up the total exposure time +then the single exposure S/N is multiplied by the square root of the number +of exposures. + + +Exposure Time From Signal-to-Noise Ratio + +If no exposure time is specified, that is a value of INDEF, then +the exposure time required to reach a desired signal-to-noise ratio +per pixel is determined. The computation is done at the specified central +wavelength. The task iterates, starting with the specified maximum time per +exposure, by computing the S/N and adjusting the exposure time +(possibly breaking the total exposure up into subexposures) until +the computed S/N matches the desired S/N to 0.1%. + +In addition to breaking the exposure time into individual exposure less +than the maximum per exposure, the task will break single exposures that +exceed the specified saturation and maximum data number values at the +reference wavelength. If other wavelengths are then saturated or exceed +the data maximum a warning is printed. +.endhelp diff --git a/noao/obsutil/src/doc/starfocus.hlp b/noao/obsutil/src/doc/starfocus.hlp new file mode 100644 index 00000000..351bf14c --- /dev/null +++ b/noao/obsutil/src/doc/starfocus.hlp @@ -0,0 +1,820 @@ +.help starfocus Nov01 noao.obsutil +.ih +NAME +starfocus -- Measure focus variations using stellar images +.ih +USAGE +starfocus images +.ih +PARAMETERS +.ls images +List of images. The images may be either taken at a sequence +of focus values or be multiple shifted exposures at a sequence of +focus settings. +.le +.ls focus = "1x1" +If the parameter \fIfstep\fR is not set (a "" null string) then this +parameter is interpreted as either a list of focus values or an +image header keyword to one focus value per image. A list may be an explicit +list of values, a range specification, or an @ file containing the values. +If there is only a single exposure per image then the focus list gives one +value per image while if there are multiple exposures per image the list +applies to the multiple exposures with the same values reused for other +images. If the parameter \fIfstep\fR is given then this parameter is +interpreted as a single starting focus value and the focus step +defines the increment between subsequent single exposure images or +for the various exposures in a multiple exposure image. +.le +.ls fstep = "" +A focus increment value or an image header keyword to the focus increment. +.le + +.ls nexposures = "1" +The number of exposures per image specified either as a value or as +an image header keyword. A double step gap in a multiple +exposure sequence does not count as an exposure. +.le +.ls step = "30." +The step in pixels between exposures specified either as a value or +as an image header keyword. +.le +.ls direction = "-line" (-line|+line|-column|+column) +The direction of the exposure sequence in the image. The values are +"-line" for successive object images appearing at smaller line numbers, +"+line" for objects appearing at larger line numbers, "-column" for +objects appearing at smaller column numbers, and "+column" for objects +appearing at larger column numbers. +.le +.ls gap = "end" (none|beginning|end) +Location of a double step gap in a sequence with the specified direction. +The available cases are "none" for an even sequence with no gap, +"beginning" where a double step is taken between the first and +the second exposure, and "end" where a double step is taken before +the last exposure. Note that "beginning" and "end" are defined in +terms of the \fIdirection\fR parameter. +.le + +.ls coords = "mark1" (center|mark1|markall) +Method by which the coordinates of objects to be measured are specified. +If "center" then a single object at the center of each image is measured. +If "mark1" then the \fIimagecur\fR parameter, typically the interactive +image display cursor, defines the coordinates of one or more objects in the +first image ending with a 'q' key value and then the same coordinates are +automatically used in subsequent images. If "markall" then the +\fIimagecur\fR parameter defines the coordinates for objects in each image +ending with a 'q' key value. +.le +.ls wcs = "logical" (logical|physical|world) +Coordinate system for input coordinates. When using image cursor input +this will always be "logical". When using cursor input from a file this +could be "physical" or "world". +.le +.ls display = yes, frame = 1 +Display the image or images as needed? If yes the image display is checked +to see if the image is already in one of the display frames. If it is not +the \fBdisplay\fR task is called to display the image in the frame +specified by the \fBframe\fR parameter. All other display parameters are +taken from the current settings of the task. This option requires that the +image display be active. A value of no is typically used when an input +cursor file is used instead of the image display cursor. An image display +need not be active in that case. +.le + +.ls level = 0.5 +The parameter used to quantify an object image size is the radius from the +image center enclosing the fraction of the total flux given by this +parameter. If the value is greater than 1 it is treated as a percentage. +.le +.ls size = "FWHM" (Radius|FWHM|GFWHM|MFWHM) +There are four ways the PSF size may be shown in graphs and given in +the output. These are: + +.nf + Radius - the radius enclosing the specified fraction of the flux + FWHM - a direct FWHM from the measured radial profile + GFWHM - the FWHM of the best fit Gaussian profile + MFWHM - the FWHM of the best fit Moffat profile +.fi + +The labels in the graphs and output will be the value of this parameter +to distinguish the different types of size measurements. +.le +.ls beta = INDEF +For the Moffat profile fit (size = MFWHM) the exponent parameter may +be fixed at a specified value or left free to be determined from the +fit. The exponent parameter is determined by the fit if \fIbeta\fR +task parameter is INDEF. +.le +.ls scale = 1. +Pixel scale in user units per pixel. Usually the value is 1 to measure +sizes in pixels or the image pixel scale in arc seconds per pixel. +.le +.ls radius = 5., iterations = 2 +Measurement radius in pixels and number of iterations on the radius. The +enclosed flux profile is measured out to this radius. This radius may be +adjusted if the \fIiteration\fR parameter is greater than 1. In that case +after each iteration a new radius is computed from the previous FWHM +estimate to be the radius the equivalent gaussian enclosing 99.5% of the +light. The purpose of this is so that if the initial PSF size of the image +need not be known. However, the radius should then be larger than true +image size since the iterations best converge to smaller values. +.le +.ls sbuffer = 5, swidth = 5. +Sky buffer and sky width in pixels. The buffer is added to the specified +measurement \fIradius\fR to define the inner radius for a circular sky +aperture. The sky width is the width of the circular sky aperture. +.le +.ls saturation=INDEF, ignore_sat=no +Data values (prior to sky subtraction) to be considered saturated within +measurement radius. A value of INDEF treats all pixels as unsaturated. If +a measurement has saturated pixels there are two actions. If +\fIignore_sat\fR=no then a warning is given but the measurement is saved +for use. The object will also be indicated as saturated in the output +log. If \fIignore_sat\fR=yes then a warning is given and the object is +discarded as if it was not measured. In a focus sequence only the +saturated objects are discarded and not the whole sequence. +.le +.ls xcenter = INDEF, ycenter = INDEF +The optical field center of the image given in image pixel coordinates. +These values need not lie in the image. If INDEF the center of the image +is used. These values are used to make plots of size verse distance from +the field center for studies of radial variations. +.le +.ls logfile = "logfile" +File in which to record the final results. If no log file is desired a +null string may be specified. +.le + +.ls imagecur = "" +Image cursor input for the "mark1" and "markall" options. If null then the +image dispaly cursor is used interactively. If a file name is specified +then the coordinates come from this file. The format of the file are lines +of x, y, id, and key. Values of x an y alone may be used to select objects +and the single character 'q' (or the end of the file) may be used to end +the list. +.le +.ls graphcur = "" +Graphics cursor input. If null then the standard graphics cursor +is used otherwise a standard cursor format file may be specified. +.le +.ih +CURSOR COMMANDS +When selecting objects with the image cursor the following commands are +available. + +.nf +? Page cursor command summary +g Measure object and graph the results. +m Measure object. +q Quit object marking and go to next image. + At the end of all images go to analysis of all measurements. + +:show Show current results. +.fi + +When in the interactive graphics the following cursor commands are available. +All plots may not be available depending on the number of focus values and +the number of stars. + +.nf +? Page cursor command summary +a Spatial plot at a single focus +b Spatial plot of best focus values +d Delete star nearest to cursor +e Enclosed flux for stars at one focus and one star at all focus +f Size and ellipticity vs focus for all data +i Information about point nearest the cursor +m Size and ellipticity vs relative magnitude at one focus +n Normalize enclosed flux at x cursor position +o Offset enclosed flux to by adjusting background +p Radial profiles for stars at one focus and one star at all focus +q Quit +r Redraw +s Toggle magnitude symbols in spatial plots +t Size and ellipticity vs radius from field center at one focus +u Undelete all deleted points +x Delete nearest point, star, or focus (selected by query) +z Zoom to a single measurement +<space> Step through different focus or stars in current plot type + + +:beta <val> Beta parameter for Moffat fit +:level <val> Level at which the size parameter is evaluated +:overplot <y|n> Overplot the profiles from the narrowest profile? +:radius <val> Change profile radius +:show <file> Page all information for the current set of objects +:size <type> Size type (Radius|FWHM) +:scale <val> Pixel scale for size values +:xcenter <val> X field center for radius from field center plots +:ycenter <val> Y field center for radius from field center plots + +The profile radius may not exceed the initial value set by the task +parameter. +.fi +.ih +DESCRIPTION +This task measures the point-spread function (PSF) width of stars or other +unresolved objects in digital images. The width is measured based on the +circular radius which encloses a specified fraction of the background +subtracted flux. The details of this are described in the ALGORITHMS +section. When a sequence of images or multiple exposures in a single image +are made with the focus varied the program provides an estimate of the best +focus and various views of how the PSF width varies with focus and position +in the image. A single star may be measured at each focus or measurements +of multiple stars may be made and combined. The task has three stages; +selecting objects and measuring the PSF width and other parameters, an +interactive graphical analysis, and a final output of the results to the +terminal and to a logfile. + +If a saturation value is specified then all pixels within the specified +measurement radius are checked for saturation. If any saturated pixels are +found a warning is given and \fIignore_sat\fR parameter may be used ot +ignore the measurement. If not ignored the object will still be indicated +as saturated in the output log. In a focus sequence only the saturated +objects are discarded and not the whole sequence. + +The input images are specified by an image template list. The list may +consist of explicit image names, wildcard templates, and @ files. A +"focus" value or values is associated with each image; though this may be +any numeric quantity (integer or floating point) and not just a focus. The +focus values may be specified in several ways. If each image has a focus +value recorded in the image header, the keyword name may be specified. If +the images consists of multiple exposures the \fIfstep\fR parameter would +specify a second image header keyword (or constant value) giving the +focus increment per exposure. + +The focus values may also be specified as a range list +as described in the help topic \fBranges\fR. This consists of +individual values, ranges of values, a starting value and a step, and a +range with a step. The elements of the list are separated by commas, +ranges are separated by hyphens, and a step is indicated by the character +'x'. Long range lists, such as a list of individual focus values, may be +placed in a file and specified with the @<filename> convention. The +assignment of a focus value from a list depends on whether the images +are single or multiple exposure as specified by the \fInexposure\fR +parameter. Single exposure images are assigned focus values from the +list in the order in which the images and focus values are given. If +the images are multiple exposure focus frames in which each offset exposure +has a different focus, the focus values from the list are assigned in +order to the multiple exposures and if there are multiple images the +assignments are repeated. + +For a simple sequence of a starting focus value and focus increment, +either for multiple single exposure images or multiple exposure +images the \fIfocus\fR and \fIfstep\fR parameters by be used +togther as single values or image header keywords. Note that if +\fIfstep\fR is specified then the focus parameter is NOT interpreted +as a list. + +There are two common ways of doing focus sequences. One is to take an +exposure at each focus value. In this case the parameter \fInexposure\fR +is given the value 1. The second is to take an image with multiple +exposures where the objects in the image are shifted between exposures and +the focus is changed. In this case \fInexposure\fR is greater than 1 and +other parameters are used to specify the shift size and direction. The +\fInexposure\fR parameter may be a number of an image header keyword. + +Currently the task allows only multiple exposure shifts along either the +column or line dimension and the shifts must be the same between each +exposure except that there may be a double shift at either end of the +sequence. The shift magnitude, in pixels, is specified as either a number +or image header keyword. The shift direction is given by the +\fIdirection\fR parameter. It is specified relative to the image; i.e. it +need not be the same as the physical shifts of the telescope or detector +but depends on how the image was created. Steps in which the object +positions decrease in column or line are specified with a leading minus and +those which increase with a leading plus. The step is specified as a +positive number of pixels between exposures. Often a double shift is made +at the beginning or end of the sequence. If this is done the \fIgap\fR +parameter is used to identify which end the gap is on. Note that one may +change the sense of the exposure sequence from that used to make the focus +frame by properly adjust the direction, the gap, the focus list, and which +object is marked as the start of the sequence. + +Identifying the object or objects to be measured may be accomplished in +several ways. If a single object near the center of the image is to be +measured then the \fIcoords\fR parameter takes the value "center". This +may be used with multiple exposure focus frames if the first exposure of +the object sequence is at the center. When the "center" option is used +the \fIdisplay\fR and \fIimagecur\fR parameters are ignored. + +If there are multiple objects or the desired object is not at the center of +the frame the object coordinates are entered with the \fIimagecur\fR +parameter. This type of coordinate input is selected by specifying either +"mark1" or "markall" for the \fIcoords\fR parameter. If the value is +"mark1" then the coordinates are entered for the first image and the same +values are automatically used for subsequent images. If "markall" is +specified then the objects in each image are marked. + +Normally the \fIimagecur\fR parameter would select the interactive image +display cursor though a standard cursor file could be used to make this +part noninteractive. When the image display cursor is used either the +image must be displayed previously by the user, or the task may be allowed +to load the image display using the \fBdisplay\fR task by setting the +parameter \fIdisplay\fR to yes and \fIframe\fR to a display frame. If yes +the image display must be active. The task will look at the image names as +stored in the image display and only load the display if needed. + +If one wants to enter a coordinate list rather than use the interactive +image cursor the list can consist of just the column and line coordinates +since the key will default to 'm'. To finish the list either the end +of file may be encountered or a single 'q' may be given since the +coordinates are irrelevant. For the "markall" option with multiple +images there would need to be a 'q' at the end of each object except +possibly the last. + +When objects are marked interactively with the image cursor there +are a four keys which may be used as shown in the CURSOR COMMAND section. +The important distinction is between 'm' to mark and measure an +object and 'g' to mark, measure, and graph the results. The former +accumulates the results until the end while the latter can give an +immediate result to be examined. Unless only one object is marked +the 'g' key also accumulates the results for later graphical analysis. +It is important to note that the measurements are done as each +object is marked so there can be a significant delay before the +next object may be marked. + +The quantities measured and the algorithms used are described in the +ALGORITHMS section. Once all the objects have been measured an +interactive (unless only one object is measured) graphical presentation +of the measurements is entered. + +When the task exits it prints the results to the terminal (STDOUT) +and also to the \fIlogfile\fR if one is specified. The results may +also be previewed during the execution of the task with the +":show" command. The results begin with a banner and the overall +estimate of the best focus and PSF size. If there are multiple +stars measured at multiple focus values the best focus estimate +for each star is printed. The star is identified by it's position +(the starting position for multiple exposure images). The average +size, relative magnitude, and best focus estimate are then given. +If there are multiple focus values the average of the +PSF size over all objects at each focus are listed next. +Finally, the individual measurements are given. The columns +give the image name, the column and line position, the relative +magnitude, the focus value, the PSF size as either the enclosed +flux radius or the FWHM, the ellipticity, the position angle, and +an indication of saturation. +.ih +ALGORITHMS +The PSF of an object is characterized using a radially symmetric +enclosed flux profile. First the center of the object is determined from +an initial rough coordinate. The center is computed from marginal profiles +which are sums of lines or columns centered at the initial coordinate and +with a width given by the sum of the \fIradius\fR, \fIsbuffer\fR, and +\fIswidth\fR parameters. The mean of the marginal profile is determined +and then the centroid of the profile above this is computed. The centroids +from the two marginal profiles define a new object center. These steps of +forming the marginal profiles centered at the estimated object position and +then computing the centroids are repeated until the centroids converge or +three iterations have been completed. + +Next a background is determined from the mode of the pixel values in the +sky annulus defined by the object center and \fIradius\fR, \fIsbuffer\fR, +and \fIswidth\fR parameters. The pixel values in the annulus are sorted +and the mode is estimated as the point of minimum slope in this sorted +array using a width of 5% of the number of points. If there are multiple +regions with the same minimum slope the lowest pixel value is used. + +The background subtracted enclosed flux profile is determined next. +To obtain subpixel precision and to give accurate estimates for small +widths relative to the pixel sampling, several things are done. +First interpolation between pixels is done using a cubic spline surface. +The radii measured are in subpixel steps. To accommodate small and +large PSF widths (and \fIradius\fR parameters) the steps are nonuniform +with very fine steps at small radii (steps of 0.05 pixels in the +central pixel) and coarser steps at larger radii (beyond 9 pixels +the steps are one pixel) out to the specified \fIradius\fR. Similarly each +pixel is subsampled finely near the center and more coarsely at larger +distances from the object center. Each subpixel value, as obtained by +interpolation, is background subtracted and added into the enclosed flux +profile. Even with subpixel sampling there is still a point where a +subpixel straddles a particular radius. At those points the fraction of +the subpixel dimension in radius falling within the radius being measured +is used as the fraction of the pixel value accumulated. + +Because of errors in the background determination due to noise and +contaminating objects it is sometimes the case that the enclosed flux +is not completely monotonic with radius. The enclosed flux +normalization, and the magnitude used in plots and reported in +results, is the maximum of the enclosed flux profile even if it +occurs at a radius less than the maximum radius. It is possible +to change the normalization and subtract or add a background correction +interactively. + +Because a very narrow PSF will produce significant errors in the cubic +spline interpolation due to the steepness and rapid variation in the pixel +values near the peak, the Gaussian profile with FWHM that encloses the same +80% of the flux is computed as: + + FWHM(80%) = 2 * r(80%) * sqrt (ln(2) / (ln (1/.2))) + +If this is less than five pixels the Gaussian model is subtracted from the +data. The Gaussian normalization is chosed to perfectly subtract the +central pixel. The resulting subtraction will not be perfect but the +residual data will have much lower amplitudes and variations. A spline +interpolation is fit to this residual data and the enclosed flux profile is +recomputed in exactly the same manner as previously except the subpixel +intensity is evaluated as the sum of the analytic Gaussian and the +interpolation to the residual data. + +The Gaussian normalization is chosed to perfectly subtract the central +pixel. The resulting subtraction will not be perfect but the residual data +will have much lower amplitudes and variations. A spline interpolation is +fit to this residual data and the enclosed flux profile is recomputed in +exactly the same manner as previously except the subpixel intensity is +evaluated as the sum of the analytic Gaussian and the interpolation to the +residual data. This technique yields accurate FWHM for simulated Gaussian +PSFs down to at least a FWHM of 1 pixel. + +In addition to the enclosed flux profile, an estimate of the radially +symmetric intensity profile is computed from the enclosed flux profile. +This is based on the equation + +.nf + F(R) = integral from 0 to R { P(r) r dr } +.fi + +where F(R) is the enclosed flux at radius R and P(r) is the intensity per +unit area profile. Thus the derivative of F(R) divided by R gives an +estimate of P(R). + +Cubic spline interpolation functions are fit to the normalized enclosed +flux profile and the intensity profile. These are used to find the radius +enclosing any specified fraction of the flux and to find the direct FWHM of +the intensity profile. These are output when \fIsize\fR is "Radius" or +"FWHM" respectively. + +In addition to enclosed flux radius and direct FWHM size measurements +there are also two size measurements based on fitting analytic profiles. +A Gaussian profile and a Moffat profile are fit to the final enclosed flux +profile to the points with enclosed flux less than 80%. The limit is +included to minimize the effects of poor background values and to make the +profile fit be representative of the core of the PSF profile. These profiles +are fit whether or not the selected \fIsize\fR requires it. This is done +for simplicity and to allow quickly changing the size estimate with the +":size" command. + +The intensity profile functions (with unit peak) are: + +.nf + I(r) = exp (-0.5 * (r/sigma)**2) Gaussian + I(r) = (1 + (r/alpha)**2)) ** (-beta) Moffat +.fi + +with parameters sigma, alpha, and beta. The normalized enclosed flux +profiles, which is what is actually fit, are then: + +.nf + F(r) = 1 - exp (-0.5 * (r/sigma)**2) Gaussian + F(r) = 1 - (1 + (r/alpha)**2)) ** (1-beta) Moffat +.fi + +The fits determine the parameters sigma or alpha and beta (if a +beta value is not specified by the users). The reported FWHM values +are given by: + +.nf + GFWHM = 2 * sigma * sqrt (2 * ln (2)) Gaussian + MFWHM = 2 * alpha * sqrt (2 ** (1/beta) - 1) Moffat +.fi + +were the units are adjusted by the pixel scale factor. + +In addition to the four size measurements there are several additional +quantities which are determined. +Other quantities which are computed are the relative magnitude, +ellipticity, and position angle. The magnitude of an individual +measurement is obtained from the maximum flux attained in the enclosed +flux profile computation. Though the normalization and background may be +adjusted interactively later, the magnitude is not changed from the +initial determination. The relative magnitude of an object is then +computed as + +.nf + rel. mag. = -2.5 * log (object flux / maximum star flux) +.fi + +The maximum star magnitude over all stars is used as the zero point for the +relative magnitudes (hence it is possible for an individual object relative +magnitude to be less than zero). + +The ellipticity and positional angle of an object are derived from the +second central intensity weighted moments. The moments are: + +.nf + Mxx = sum { (I - B) * x * x } / sum { I - B } + Myy = sum { (I - B) * y * y } / sum { I - B } + Mxy = sum { (I - B) * x * y } / sum { I - B } +.fi + +where x and y are the distances from the object center, I is +the pixel intensity and B is the background intensity. The sum is +over the same subpixels used in the enclosed flux evaluation with +intensities above an isophote which is slightly above the background. +The ellipticity and position angles are derived from the moments +by the equations: + +.nf + M1 = (Mxx - Myy) / (Mxx + Myy) + M2 = 2 * Mxy / (Mxx + Myy) + ellip = (M1**2 + M2**2) ** 1/2 + pa = atan (M2 / M1) / 2 +.fi + +where ** is the exponentiation operator and atan is the arc tangent +operator. The ellipticity is essentially (a - b) / (a + b) where a +is a major axis scale length and b is a minor axis scale length. A +value of zero corresponds to a circular image. The position angle is +given in degrees counterclockwise from the x or column axis. + +The overall size when there are multiple stars is estimated by averaging +the individual sizes weighted by the flux of the star as described above. +Thus, when there are multiple stars, the brighter stars are given greater +weight in the average size. This average size is what is given in the +banner for the graphs and in the printed output. + +One of the quantities computed for the graphical analysis is the +FWHM of a Gaussian or Moffat profile that encloses the same flux +as the measured object as a function of the level. The equation are: + +.nf + FWHM = 2 * r(level) * sqrt (ln(2.) / ln (1/(1-level))) Gaussian + + FWHM = 2 * r(level) * sqrt (2**(1/beta)-1) / + sqrt ((1-level)**(1/(1-beta))-1) Moffat +.fi + +where r(level) is the radius that encloses "level" fraction of the total +flux. ln is the natural logarithm and sqrt is the square root. The beta +value is either the user specified value or the value determined by fitting +the enclosed flux profile. + +This function of level will be a constant if the object profile matches +the Gaussian or Moffat profile. Deviations from a constant show +the departures from the profile model. The Moffat profile used in making +the graphs except for the case where the \fIsize\fR is GFWHM. + +The task estimates a value for the best focus and PSF size at that focus +for each star. This is done by finding the minimum size at each focus +value (in case there are multiple measurements of the same star at the same +focus), sorting them by focus value, finding the focus value with the +minimum size, and parabolically interpolating using the nearest focus +values on each side. When the minimum size occurs at either extreme of the +focus range the best focus is at that extreme focus; in other words there +is no extrapolation outside the range of focus values. + +The overall best focus and size when there are multiple stars are estimated +by averaging the best focus values for each star weighted by the +average flux of the star as described above. Thus, when there are +multiple stars, the brighter stars are given greater weight in the +overall best average focus and size. This best average focus and +size are what are given in the banner for the graphs and in the +printed output. + +The log output also includes an average PSF size for all measurements +at a single focus value. This average is also weighted by the +average flux of each star at that focus. +.ih +INTERACTIVE GRAPHICS MODE +The graphics part of \fBstarfocus\fR consists of a number of different +plots selected by cursor keys. The available plots depend on the +number of stars and the number of focus values. The various plots +and the keys which select them are summarized below. + +.nf +a Spatial plot at a single focus +b Spatial plot of best focus values +e Enclosed flux for stars at one focus and one star at all focus +f Size and ellipticity vs focus for all data +m Size and ellipticity vs relative magnitude at one focus +p Radial profiles for stars at one focus and one star at all focus +t Size and ellipticity vs radius from field center at one focus +z Zoom to a single measurement +.fi + +If there is only one object at a single focus the only available plot is +the 'z' or zoom plot. This has three graphs; a graph of the normalized +enclosed flux verses scaled radius, a graph of the intensity profile verses +scaled radius, and equivalent Moffat/Gaussian full width at half maximum verses +enclosed flux fraction. The latter two graphs are derived from the +normalized enclosed flux profile as described in the ALGORITHMS section. +In the graphs the measured points are shown with symbols, a smooth curve is +drawn through the symbols and dashed lines indicate the measurement level +and enclosed flux radius at that level. + +Overplotted on these graphs are the Moffat profile fit or the +Gaussian profile fit when \fIsize\fR is GFWHM. + +The zoom plot is always available from any other plot. The cursor position +when the 'z' key is typed selects a particular object measurement. +This plot is also the one presented with the 'g' key when marking objects for +single exposure images. In that case the graphs are drawn followed by +a return to image cursor mode. + +There are three types of symbol plots showing the measured PSF size (either +enclosed flux radius or FWHM) and ellipticity. These plot the measurements +verses focus ('f' key), relative magnitude ('m' key), and radius from the +field center ('t' key). The focus plot includes all measurements and shows +dashed lines at the estimated best focus and size. This plot is only +available when there are multiple focus values. It is the initial plot in +this case for both the 'g' key when there are multiple exposures and when +the graphical analysis stage is entered after defining the objects. + +The magnitude and field radius plots are only available when there are +multiple objects measured. The relative magnitude used for a particular +measurement is the average magnitude of the star over all focus values and +not the individual object magnitude. The data shown is for a single focus +value. The focus value is selected when typing 'm' or 't' by the focus of +the nearest object to the cursor in the preceding plot. When in one of +these plots, other focus values may be shown by typing <space>, the space +bar. This scrolls through the focus values. The field center for the +field radius graph may be changed interactively using the ":xcenter" and +":ycenter" commands. + +Grids of enclosed flux vs. radius, intensity profile vs. radius, and +FWHM vs. enclosed flux fraction are shown with the 'e', 'p', and +'g' keys respectively. If there are multiple objects at multiple focus +values there are two grids. One grid is all objects at one focus and the +other is one object at all focuses. The titles identify the object (by +location) and focus. The profiles in the grids have no axis labels or +ticks. Within each box are the coordinates of the object or the focus +value, and the PSF size are given. When there is only one object at +multiple focus values or multiple objects at only one focus value then +there is only one grid and a graph of a one object. The single object +graph does have axis labels and ticks. + +In the grids there is one profile which is highlighted (by a second +box or by a color border). The highlighted profile is the current +object. To change the current object, and thus change either +the contents of the other grid or the single object graphed, one +can type the space bar to advance to the next object or +use the cursor and the 'e', 'p', or 'g' key again. Other keys +will select another plot using the object nearest the cursor to select +a focus or object. + +Any of the graphs with enclosed flux or intensity profiles vs radius may +have the profiles of the object with the smallest size overplotted. The +overplot has a dashed line, a different color on color graphics devices, +and no symbols marking the measurement points. The overplots may be +enabled or disabled with the ":overplot" command. Initially it is +disabled. + +The final plots give a spatial representation. These require more than one +object. The 'a' key gives a spatial plot at a single focus. The space bar +can be used to advance to another focus. This plot has a central graph of +column and line coordinates with symbols indicating the position of an +object. The objects are marked with a circle (when plotted at unit aspect +ratio) whose size is proportional to the measured PSF size. In addition an +optional asterisk symbol with size proportional to the relative +brightness of the object may be plotted. This symbol is toggled with the +'s' key. On color displays the circles may have two colors, one if object +size is above the average best size and the other if the size is below the +best size. The purpose of this is to look for a spatial pattern in the +smallest PSF sizes. + +Adjacent to the central graph are graphs with column or line as one +coordinate and radius or ellipticity as the other. The symbols +are the same as described previously. These plots can show spatial +gradients in the PSF size and shape across the image. + +The 'b' key gives a spatial plot of the best focus estimates for each +object. This requires multiple objects and multiple focus values. +As discussed previously, given more than one focus a best focus +value and size at the best focus is computed by parabolic interpolation. +This plot type shows the object positions in the same way as the 'a' +plot except that the radius is the estimated best radius. Instead +of adjacent ellipticity plots there are plots of best focus verses +columns and lines. Also the two colors in the symbol plots are +selected depending on whether the object's best focus estimate is +above or below the overall best focus estimate. This allows seeing +spatial trends in the best focus. + +In addition to the keys which select plots there are other keys which +do various things. These are summarized below. + +.nf +? Page cursor command summary +d Delete star nearest to cursor +i Information about point nearest the cursor +n Normalize enclosed flux at x cursor position +o Offset enclosed flux by adjusting background +q Quit +r Redraw +s Toggle magnitude symbols in spatial plots +u Undelete all deleted points +x Delete nearest point, star, or focus (selected by query) +<space> Step through different focus or stars in current plot type +.fi + +The help, redraw, and quit keys are provide the standard functions. +The 's' and space keys were described previously. The 'i' key +locates the nearest object to the cursor in whatever plot is shown and +prints one line of information about the object on the graphics device +status area. + +The 'd' key deletes the star nearest the cursor in whatever plot is +currently displayed. Deleting a star deletes all measurements of an object +at different focus values. To delete all objects from an image, all focus +values for one star (the same as 'd'), all objects at one focus, or a +single measurement, the 'x' key is used. Typing this key produces a query +for which type of deletion and the user responds with 'i', 's', 'f', or +'p'. The most common use of this is to delete all objects at the extreme +focus values. Deleted measurements do not appear in any subsequent +graphics, are excluded from all computations, and are not output in the +results. The 'u' key allows one to recover deleted measurements. This +undeletes all previously deleted data. + +Due to various sources of error the sky value may be wrong causing +the enclosed flux profile to not converge properly but instead +decreases beyond some point (overestimated sky) or linearly +increases with radius (underestimated sky). This affects the size +measurement by raising or lowering the normalization and altering +the shape of the enclosed flux profile. The 'n' and 'o' keys allow +fudging the enclosed flux profiles. These keys apply only in +the zoom plot of the enclosed flux profile or the case where +a single enclosed flux profile is shown with the 'e' key; in other +words plots of the enclosed flux which have axes labels. + +The 'n' key normalizes the enclosed flux profile at the point +set by the x position of the cursor. The 'o' key increases or +decreases the background estimate to bring curve up or down to +the point specified by the cursor. The effect of this is to +add or subtract a quadratic function since the number of pixels +at a particular radius varies as the square of the radius. +To restore the original profile, type 'n' or 'o' at a radius +less than zero. + +The colon commands, shown below, allow checking or changing parameters +initially set by the task parameters, toggling the overplotting of the +smallest PSF profiles, and showing the current results. The overplotting +option and the contents of the results displayed by :show were described +previously. + +.nf +:beta <val> Beta parameter for Moffat fits +:level <val> Level at which the size parameter is evaluated +:overplot <y|n> Overplot the profiles from the narrowest profile? +:radius <val> Change profile radius +:show <file> Page all information for the current set of objects +:size <type> Size type (Radius|FWHM) +:scale <val> Pixel scale for size values +:xcenter <val> X field center for radius from field center plots +:ycenter <val> Y field center for radius from field center plots +.fi + +The important values which one might want to change interactively are +the measurement level and the profile radius. The measurement level +directly affects the results reported. When it is changed the sizes +of all object PSFs are recomputed and the displayed plots and title +information are updated. The profile radius is the +maximum radius shown in plots and used to set the enclosed flux normalization. +It does not affect the object centering or sky region definition and +evaluation which are done when the image data is accessed. Because +the objects are not remeasured from the image data the radius may +not be made larger than the radius defined by the task parameter though +it may be decreased and then increased again. +.ih +EXAMPLES +1. A multiple exposure frame is taken with 7 exposures of a bright +star, each exposure shifted by 50 pixels to lower line positions, with a +double gap at the end. The exposure pattern is typical of Kitt Peak and +the default values for the direction and gap position are applicable. The +default focus value numbering and measurements in pixels are also used. + +.nf +cl> starfocus focus1 nexp=7 step=50 +<The image is displayed and the image cursor activated> +<The bright star is marked with 'm'> +<Marking is finished with 'q'> +<A graph of FWHM vs focus index is shown> +<Exit with 'q'> +NOAO/IRAF IRAFV2.10.3 valdes@puppis Wed 16:09:39 30-Jun-93 + Best focus of 4.12073 with FWHM (at 50% level) of 3.04 + + Image Column Line Mag Focus FWHM Ellip PA SAT + focus1 536.63 804.03 0.07 1. 13.878 0.06 -11 + 535.94 753.28 -0.11 2. 8.579 0.09 89 + 535.38 703.96 -0.08 3. 5.184 0.11 -87 + 537.12 655.36 -0.02 4. 3.066 0.07 -77 + 534.20 604.59 0.00 5. 4.360 0.10 74 + 534.41 554.99 -0.00 6. 9.799 0.09 -35 + 534.83 456.08 0.16 7. 12.579 0.13 -10 +.fi + +The estimated best focus is between the 4th and 5th focus setting +and the best focus FWHM is 3.04 pixels. + +Note that in more recent Kitt Peak multiple exposure focus images the +starting focus value, the focus step, the number of exposures, and +the shift are recorded in the image header with the keywords +FOCSTART, FOCSTEP, FOCNEXPO, and FOCSHIFT. Thus the task parameters +\fIfocus\fR, \fIfstep\fR, \fInexposures\fR, and \fIstep\fR may be +set to those names. However, rather than use \fBstarfocus\fR +one would use the more convenient \fBkpnofocus\fR. +.ih +SEE ALSO +.nf +imexamine, implot, kpnofocus, pprofile, pradprof, psfmeasure, radlist, +radplt, radprof, ranges, specfocus, splot +.endhelp |