path: root/noao/twodspec/apextract/doc/apextractsys.hlp

.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