diff options
Diffstat (limited to 'noao/twodspec/apextract/doc/apextractsys.hlp')
| -rw-r--r-- | noao/twodspec/apextract/doc/apextractsys.hlp | 415 |
1 files changed, 415 insertions, 0 deletions
diff --git a/noao/twodspec/apextract/doc/apextractsys.hlp b/noao/twodspec/apextract/doc/apextractsys.hlp new file mode 100644 index 00000000..a93d9f56 --- /dev/null +++ b/noao/twodspec/apextract/doc/apextractsys.hlp @@ -0,0 +1,415 @@ +.help apextract Aug90 noao.twodspec.apextract + +.ce +APEXTRACT System Notes + + +\fBIntroduction\fR + +The \fBapextract\fR package is a complex package with a simple +purpose, the extraction of one dimensional spectra from two dimensional +images. The complexity arises from the many algorithms and parameters +involved. To manage the complexity of the algorithms, features, parameters, +functionality, and documentation the package has been organized in terms +of logical functions which may be invoked in a number of ways. The +logical functions are: +.ls o +Automatically find a specified number of spectra and assign default +apertures. Apertures may also be inherited from another image or +defined using an interactive graphical interface called the \fIaperture +editor\fR. +.le +.ls o +Recenter apertures on the image spectrum profiles. +.le +.ls o +Resize apertures based on spectrum profile width. +.le +.ls o +Interactively define or adjust aperture definitions using a graphical +interface called the \fIaperture editor\fR. All function may also +be performed from this editor and, so, provides an alternative +method of processing and extracting spectra. +.le +.ls o +Trace the positions of spectra profiles from a starting image line +or column to other image lines or columns and fit a smooth function. +The trace function is used to shift the center of the apertures +at each dispersion point in the image. +.le +.ls o +Extract the flux in the apertures into one dimensional spectra in various +formats. This includes possible background subtraction, variance +weighting, and bad pixel rejection. +.le + +The package is logically organized around these functions. Each +function has a task devoted to it. The description of the parameters +and algorithms for each function are organized according to these +tasks; namely under the help topics \fBapdefault, apfind, aprecenter, +apresize, apedit, aptrace\fR, and \fBapsum\fR. However, each task has +parameters to allow selecting some or all of the other functions, hence +it is not necessary to use the individual tasks and often it is more +convenient to use just the extraction task for all operations. It is +also possible to perform all the functions from within a graphical +interface called the aperture editor. This is usually only used to +define and modify aperture definitions but it also has the capability +to trace spectra and extract them. + +Each of the functions has many different options and parameters. When +broken down into individual tasks the parameters are also sorted by +their function though there are then some mutual interdependencies. +This parameter decomposition was what was available prior to the +addition of the task \fBapall\fR. This is the central task of the +package which performs any and all of the functions required for the +extraction of spectra and also collects all the parameters into one +parameter set. It is recommended that \fBapall\fR be used because it +collects all the parameters in one place eliminating confusion over +where a particular parameter is defined. + +In summary, the package consists of a number of logical functions which +are documented by the individual tasks named for that function, but the +functions are also integrated into each task and the aperture editor to +providing many different ways for the user to choose to perform the +functions. + +This document describes some of the implementation details and features +which are hidden from the normal user. + + +\fBParameters\fR + +The tasks actually use hidden parameter sets for almost all parameters. +To see all the parameter sets type + +.nf + ap> ?_ apextract +.fi + +The relation between the tasks and the hidden parameter sets is given below. + +.nf + PSET TASK + apparams - apdefault, apfind, aprecenter, apresize, + apedit, aptrace, apsum, apmask, apscatter + apall1 - apall + apfit1 - apfit + apflat1 - apflatten + apnorm1 - apnormalize +.fi + +The hidden parameter sets may be viewed in any of the normal ways +\fBeparam\fR, \fBlparam\fR, or just by typing their name, except +their names may not be abbreviated. Their purpose is to redirect +parameters to visible parameter sets, to hide some parameters which +are not meant to be changed by the user, and to include parameters +used for queries. + +Most of the redirected parameters go to a single visible parameter set +or to package parameters. +The interesting exception is \fBapparams\fR which provides the +parameter linkage between the various functional tasks like +\fBapfind\fR, \fBaptrace\fR, \fBapsum\fR, etc. Below is a reproduction +of this parameter set. + +.ce +APPARAMS Hidden Parameter Set + +.nf + I R A F + Image Reduction and Analysis Facility +PACKAGE = apextract + TASK = apparams + +(format = )_.format) Extracted spectra format +(extras = )apsum.extras) Extract sky, sigma, etc.? +(dbwrite= yes) Write to database? +(initial= yes) Initialize answers? +(verbose= )_.verbose) Verbose output? + + # DEFAULT APERTURE PARAMETERS + +(upper = )apdefault.upper) Upper aperture limit relative to center +(apidtab= )apdefault.apidtable) Aperture ID table (optional) + + # DEFAULT BACKGROUND PARAMETERS + +(b_funct= )apdefault.b_function) Background function +(b_order= )apdefault.b_order) Background function order +(b_sampl= )apdefault.b_sample) Background sample regions +(b_naver= )apdefault.b_naverage) Background average or median +(b_niter= )apdefault.b_niterate) Background rejection iterations +(b_low_r= )apdefault.b_low_reject) Background lower rejection sigma +(b_high_= )apdefault.b_high_reject) Background upper rejection sigma +(b_grow = )apdefault.b_grow) Background rejection growing radius + + # APERTURE CENTERING PARAMETERS + +(width = )apedit.width) Profile centering width +(radius = )apedit.radius) Profile centering radius +(thresho= )apedit.threshold) Detection threshold for profile centering + + # AUTOMATIC FINDING AND ORDERING PARAMETERS + +(nfind = )apfind.nfind) Number of apertures to be found automatically +(minsep = )apfind.minsep) Minimum separation between spectra +(maxsep = )apfind.maxsep) Maximum separation between spectra +(order = )apfind.order) Order of apertures + + # RECENTERING PARAMETERS + +(apertur= )aprecenter.apertures) Select apertures +(npeaks = )aprecenter.npeaks) Select brightest peaks +(shift = )aprecenter.shift) Use average shift instead of recentering? + + # RESIZING PARAMETERS + +(llimit = )apresize.llimit) Lower aperture limit relative to center +(ulimit = )apresize.ulimit) Upper aperture limit relative to center +(ylevel = )apresize.ylevel) Fraction of peak or intensity for automatic widt(peak = )apresize.peak) Is ylevel a fraction of the peak? +(bkg = )apresize.bkg) Subtract background in automatic width? +(r_grow = )apresize.r_grow) Grow limits by this factor +(avglimi= )apresize.avglimits) Average limits over all apertures? + + # EDITING PARAMETERS + +e_output= Output spectra rootname +e_profil= Profile reference image +(t_nsum = )aptrace.nsum) Number of dispersion lines to sum +(t_step = )aptrace.step) Tracing step +(t_width= )apedit.width) Centering width for tracing +(t_funct= )aptrace.function) Trace fitting function +(t_order= )aptrace.order) Trace fitting function order +(t_sampl= )aptrace.sample) Trace sample regions +(t_naver= )aptrace.naverage) Trace average or median +(t_niter= )aptrace.niterate) Trace rejection iterations +(t_low_r= )aptrace.low_reject) Trace lower rejection sigma +(t_high_= )aptrace.high_reject) Trace upper rejection sigma +(t_grow = )aptrace.grow) Trace rejection growing radius + + # EXTRACTION PARAMETERS + +(backgro= )apsum.background) Background to subtract (none|average|fit) +(skybox = )apsum.skybox) Box car smoothing length for sky +(weights= )apsum.weights) Extraction weights (none|variance) +(clean = )apsum.clean) Detect and replace bad pixels? +(niterat= 2) Number of profile fitting iterations +(saturat= )apsum.saturation) Saturation level +(readnoi= )apsum.readnoise) Read out noise sigma (photons) +(gain = )apsum.gain) Photon gain (photons/data number) +(lsigma = )apsum.lsigma) Lower rejection threshold +(usigma = )apsum.usigma) Upper rejection threshold +(maxtilt= 3) Maximum excursion for line/column fitting +(polysep= 0.95) Marsh algorithm polynomial spacing +(polyord= 10) Marsh algorithm polynomial order +(nsubaps= )apsum.nsubaps) Number of subapertures per aperture + + # ANSWER PARAMETERS + +(ansclob= no) +(ansclob= no) +(ansdbwr= yes) +(ansdbwr= yes) +(ansedit= yes) +(ansextr= yes) +(ansfind= yes) +(ansfit = yes) +(ansfits= yes) +(ansfits= yes) +(ansfits= yes) +(ansfits= yes) +(ansfitt= yes) +(ansfitt= yes) +(ansflat= yes) +(ansmask= yes) +(ansnorm= yes) +(ansrece= yes) +(ansresi= yes) +(ansrevi= yes) +(ansrevi= yes) +(ansscat= yes) +(anssmoo= yes) +(anstrac= no) +(mode = q) +.fi + +Note how the parameters are redirected to a variety of tasks. + + +\fBInvisible Parameters\fR + +The following algorithm parameters are not visible to the normal user +and are described only here. +.ls dbwrite = yes +Write to database? Writing to the database is a function just like +find, edit, extract, etc. When the task is interactive a query is +made whether to write to the database which may be answered with the +usual four values. When noninteractive the database writing is automatic. +This parameter provides the possibility of turning off database writing. +.le +.ls initialize = yes +Initialize default queries? Normally each invocation of a task results +in new queries independent of the last responses in a prior invocation +and based only on the functions selected; NO for those not selected and +yes for those selected. By setting this to no either the prior values +may be used or the response values may be set independently of the +function flags. This is used in scripts to tie together different +invocations of the task and to finely control the queries. +.le +.ls e_output, e_profile +These are query parameters used when extraction is invoked from the +aperture editor. +.le + +The following parameters are part of the variance weighted and cleaning +extractions. They are described further in \fBapprofiles\fR. +.ls niterate = 2 +Number of rejection iterations in the profile determination when cleaning. +Iteration of the profile is slow and the low order fitting function +is not very sensitive to deviant points. +.le +.ls maxtilt = 3 +Maximum excursion separating the two profile fitting algorithms. +.le +.ls polysep = 0.95 +Marsh algorithm polynomial spacing. +.le +.ls polyorder = 10 +Marsh algorithm polynomial order. +.le + + +\fBQuery Mechanism and Invisible Query Parameters\fR + +The querying mechanism of the \fBapextract\fR package is a nice feature +but has some complexities in implementation. At the bottom of the +mechanism are CL checks of the parameters described below. The parameter +is accessed first as a hidden parameter. If the value is YES or NO +then the appropriate function is performed or not. If the value is +lower case then the task supplies a prompt string, which varies by +including the image and/or aperture involved, the mode of the +parameter is changed to query, and the parameter is requested again +leading to a CL query of the user with the current default value. +Finally, the parameter is returned to hidden mode. + +If the \fIinitialize\fR parameter is no then the initial default +query values are those set before the task is invoked. This provides +very fine control of the query mechanism and linking different +invocations of the tasks to previous user responses. It is intended +only for complex scripts such as those in the spectroscopic \fBimred\fR +packages. Normally the initial values of the parameters are set +during task startup based on the function flags. If a flag is no +then the related query parameter is NO. If the function flag is yes +then when the task is interactive the initial value is yes otherwise +it is YES. The solely interactive functions, such as editing, are +set to NO when the task is noninteractive regardless of the function +selection. +.ls ansclobber, ansclobber1 +Used to define the action to be taken if an output image would be clobbered. +Normally the action is to query if interactive and not clobber if +noninteractive. The first parameter acts as the function switch and +the second as the actual query. +.le +.ls ansdbwrite, ansdbwrite1 +The second parameter is used by the task to mark whether any changes have +been made that might require a database update. The first parameter is +the actual query parameter for the \fIdbwrite\fR function flag. +.le +.ls ansedit +Query parameter for the interactive editing function. +.le +.ls ansextract +Query parameter for the extraction function. +.le +.ls ansfind +Query parameter for the find function. +.le +.ls ansfit +Query parameter for the fit function of \fBapfit\fR. +.le +.ls ansfitscatter +Query parameter for the interactive fitscatter function of \fBapscatter\fR. +.le +.ls ansfitsmooth +Query parameter for the interactive fitsmooth function of \fBapscatter\fR. +.le +.ls ansfitspec +Query parameter for the interactive fitspec function of \fBapflatten\fR +and \fBapnormalize\fR. This applies to each image. +.le +.ls ansfitspec1 +Query parameter for the interactive fitspec function of \fBapflatten\fR +and \fBapnormalize\fR. This applies to each aperture in an image. +.le +.ls ansfittrace +Query parameter for the interactive fittrace function. +This applies to each image. +.le +.ls ansfittrace1 +Query parameter for the interactive fittrace function. +This applies to each aperture in an image. +.le +.ls ansflat +Query parameter for the flatten function of \fBapflatten\fR. +.le +.ls ansmask +Query parameter for the mask function of \fBapmask\fR. +.le +.ls ansnorm +Query parameter for the normalize function of \fBapnormalize\fR. +.le +.ls ansrecenter +Query parameter for the recenter function. +.le +.ls ansresize +Query parameter for the resize function. +.le +.ls ansreview +Query parameter for the interactive extraction review function. +This applies to each image. +.le +.ls ansreview1 +Query parameter for the interactive extraction review function. +This applies to each aperture in an image. +.le +.ls ansscat +Query parameter for the subtract function of \fBapscatter\fR. +.le +.ls anssmooth +Query parameter for the smooth function of \fBapscatter\fR. +.le +.ls anstrace +Query parameter for the trace function. +.le + + +\fBTask Entry Points\fR + +Logical tasks in IRAF are organized as multiple procedures in one physical +task selected by the IRAF main. The \fBapextract\fR package extends +this concept to a lower level. All of the package tasks go through +one procedure, \fBapall\fR. This procedure handles all of the +startup details and breaks the logical task down into selected +functions which are implemented as other procedures. There are +a couple of interesting and unusual features of this organization. + +IRAF physical tasks may map multiple logical task names to the same +procedure. However, the procedure will not know under what name it +was called. In this package we want to know the logical task name +in order to select the appropriate hidden parameter set and to +make minor adjustments in what the tasks do while maintaining the +same basic logical flow and source code. To do this dummy entry +points are used whose only function is to call \fBapall\fR and +pass an indication of the task name. + +Based on the task name a named parameter set is opened with \fBclopset\fR +and then all CLIO calls use the returned pointer and can be blind to the +actual parameter set used. + +In addition to the tasks defined in the package and their associated +parameter sets there is one more task entry point called \fBapscript\fR +with parameter set \fBapscript\fR. It is intended for use in scripts +as it's name implies. For this reason it does not need an intermediate +hidden parameter set. For examples of it's use see the \fBimred\fR +packages such as \fBnessie\fR. +.endhelp |