apall input
input
List of input images.
output =
List of output root names for extracted spectra. If the null
string is given or the end of the output list is reached before the end
of the input list then the input image name is used as the output root name.
This will not conflict with the input image since an aperture number
extension is added for onedspec format, the extension ".ms" for multispec
format, or the extension ".ec" for echelle format.
format = multispec (onedspec|multispec|echelle|strip)
Format for output extracted spectra. "Onedspec" format extracts each
aperture to a separate image while "multispec" and "echelle" extract
multiple apertures for the same image to a single output image.
The "multispec" and "echelle" format selections differ only in the
extension added. The "strip" format produces a separate 2D image in
which each column or line along the dispersion axis is shifted to
exactly align the aperture based on the trace information.
references =
List of reference images to be used to define apertures for the input
images. When a reference image is given it supersedes apertures
previously defined for the input image. The list may be null, "", or
any number of images less than or equal to the list of input images.
There are three special words which may be used in place of an image
name. The word "last" refers to the last set of apertures written to
the database. The word "OLD" requires that an entry exist
and the word "NEW" requires that the entry not exist for each input image.
Input images without/with a database entry are skipped silently.
profiles =
List of profile images for variance weighting or cleanning. If variance
weighting or cleanning a profile of each aperture is computed from the
input image unless a profile image is specified, in which case the
profile is computed from the profile image. The profile image must
have the same dimensions and dispersion and it is assumed that the
spectra have the same position and profile shape as in the object
spectra. Use of a profile image is generally not required even for
faint input spectra but the option is available for those who wish
to use it.
find = yes
Find the spectra and define apertures automatically? In order for
spectra to be found automatically there must be no apertures for the
input image or reference image defined in the database.
recenter = no
Recenter the apertures?
resize = no
Resize the apertures?
edit = yes
Edit the apertures? The interactive parameter must also be yes.
trace = yes
Trace the apertures?
fittrace = yes
Interactively fit the traced positions by a function? The interactive
parameter must also be yes.
extract = yes
Extract the one dimensional aperture sums?
extras = no
Extract the raw spectrum (if variance weighting is used), the sky spectrum
(if background subtraction is used), and variance spectrum (if variance
weighting is used)? This information is extracted to the third dimension
of the output image.
review = yes
Review the extracted spectra? The interactive parameter must also be
yes.
line = INDEF, nsum = 1
The dispersion line (line or column perpendicular to the dispersion
axis) and number of adjacent lines (half before and half after unless
at the end of the image) used in finding, recentering, resizing,
and editing operations. A line of INDEF selects the middle of the
image along the dispersion axis. A positive nsum selects a sum of
lines and a negative selects a median of lines.
apidtable =
Aperture identification table consisting of lines with an aperture number,
a beam number, and a title. This table is used to assign aperture
information automatically in apfind and apedit.
b_order = 1
Default background function order. The order refers to the number of
terms in the polynomial functions or the number of spline pieces in the spline
functions.
b_sample = -10:-6,6:10
Default background sample. The sample is given by a set of colon separated
ranges each separated by either whitespace or commas. The string "*" refers
to all points. Note that the background coordinates are relative to the
aperture center and not image pixel coordinates so the endpoints need not
be integer.
b_naverage = -3
Default number of points to average or median. Positive numbers
average that number of sequential points to form a fitting point.
Negative numbers median that number, in absolute value, of sequential
points. A value of 1 does no averaging and each data point is used in the
fit.
b_niterate = 0
Default number of rejection iterations. If greater than zero the fit is
used to detect deviant fitting points and reject them before repeating the
fit. The number of iterations of this process is given by this parameter.
b_low_reject = 3., b_high_reject = 3.
Default background lower and upper rejection sigmas. If greater than zero
points deviating from the fit below and above the fit by more than this
number of times the sigma of the residuals are rejected before refitting.
b_grow = 0.
Default reject growing radius. Points within a distance given by this
parameter of any rejected point are also rejected.
radius = 10.
The profile centering error radius for the centering algorithm.
threshold = 0.
Centering threshold for the centering algorithm. The range of pixel intensities
near the initial centering position must exceed this threshold.
minsep = 5.
Minimum separation between spectra. Weaker spectra or noise within this
distance of a stronger spectrum are rejected.
maxsep = 1000.
Maximum separation between adjacent spectra. This parameter
is used to identify missing spectra in uniformly spaced spectra produced
by fiber spectrographs. If two adjacent spectra exceed this separation
then it is assumed that a spectrum is missing and the aperture identification
assignments will be adjusted accordingly.
order = increasing
When assigning aperture identifications order the spectra "increasing"
or "decreasing" with increasing pixel position (left-to-right or
right-to-left in a cross-section plot of the image).
npeaks = INDEF
Select the specified number of apertures with the highest peak values
to be recentered. If the number is INDEF all apertures will be selected.
If the value is less than 1 then the value is interpreted as a fraction
of total number of apertures.
shift = yes
Use the average shift from recentering the selected apertures to apply to
all apertures. The recentering is then a constant shift for all apertures.
ylevel = 0.1
Data level at which to set aperture limits. If it is INDEF then the
aperture limits are set at the values given by the parameters
llimit and ulimit. If it is not INDEF then it is a
fraction of the peak or an actual data level depending on the parameter
peak. It may be relative to a local background or to zero
depending on the parameter bkg.
peak = yes
Is the data level specified by ylevel a fraction of the peak?
bkg = yes
Subtract a simple background when interpreting the ylevel parameter.
The background is a slope connecting the first inflection points
away from the aperture center.
r_grow = 0.
Change the lower and upper aperture limits by this fractional amount.
The factor is multiplied by each limit and the result added to limit.
avglimits = no
Apply the average lower and upper aperture limits to all apertures.
t_step = 10
Step along the dispersion axis between determination of the spectrum
positions.
t_nlost = 3
Number of consecutive steps in which the profile is lost before quitting
the tracing in one direction. To force tracing to continue through
regions of very low signal this parameter can be made large. Note,
however, that noise may drag the trace away before it recovers.
t_function = legendre
Default trace fitting function. The fitting function types are
"chebyshev" polynomial, "legendre" polynomial, "spline1" linear spline, and
"spline3" cubic spline.
t_order = 2
Default trace function order. The order refers to the number of
terms in the polynomial functions or the number of spline pieces in the spline
functions.
t_sample = *
Default fitting sample. The sample is given by a set of colon separated
ranges each separated by either whitespace or commas. The string "*" refers
to all points.
t_naverage = 1
Default number of points to average or median. Positive numbers
average that number of sequential points to form a fitting point.
Negative numbers median that number, in absolute value, of sequential
points. A value of 1 does no averaging and each data point is used in the
t_niterate = 0
Default number of rejection iterations. If greater than zero the fit is
used to detect deviant traced positions and reject them before repeating the
fit. The number of iterations of this process is given by this parameter.
t_low_reject = 3., t_high_reject = 3.
Default lower and upper rejection sigma. If greater than zero traced
points deviating from the fit below and above the fit by more than this
number of times the sigma of the residuals are rejected before refitting.
t_grow = 0.
Default reject growing radius. Traced points within a distance given by this
parameter of any rejected point are also rejected.
weights = none (none|variance)
Type of extraction weighting. Note that if the clean parameter is
set then the weights used are "variance" regardless of the weights
specified by this parameter. The choices are:
none
The pixels are summed without weights except for partial pixels at the
ends.
variance
The extraction is weighted by the variance based on the data values
and a poisson/ccd model using the gain and readnoise
parameters.
pfit = fit1d (fit1d|fit2d)
Profile fitting algorithm to use with variance weighting or cleaning.
When determining a profile the two dimensional spectrum is divided by
an estimate of the one dimensional spectrum to form a normalized two
dimensional spectrum profile. This profile is then smoothed by fitting
one dimensional functions, "fit1d", along the lines or columns most closely
corresponding to the dispersion axis or a special two dimensional
function, "fit2d", described by Marsh (see approfile).
clean = no
Detect and replace deviant pixels?
skybox = 1
Box car smoothing length for sky background when using background
subtraction. Since the background noise is often the limiting factor
for good extraction one may box car smooth the sky to improve the
statistics in smooth background regions at the expense of distorting
the subtraction near spectral features. This is most appropriate when
the sky regions are limited due to a small slit length.
saturation = INDEF
Saturation or nonlinearity level in data units. During variance weighted
extractions wavelength points having any pixels above this value are
excluded from the profile determination and the sigma spectrum extraction
output, if selected by the extras parameter, flags wavelengths with
saturated pixels with a negative sigma.
readnoise = 0.
Read out noise in photons. This parameter defines the minimum noise
sigma. It is defined in terms of photons (or electrons) and scales
to the data values through the gain parameter. A image header keyword
(case insensitive) may be specified to get the value from the image.
gain = 1
Detector gain or conversion factor between photons/electrons and
data values. It is specified as the number of photons per data value.
A image header keyword (case insensitive) may be specified to get the value
from the image.
lsigma = 3., usigma = 3.
Lower and upper rejection thresholds, given as a number of times the
estimated sigma of a pixel, for cleaning.
nsubaps = 1
During extraction it is possible to equally divide the apertures into
this number of subapertures.
Dispersion axis and I/O parameters are taken from the package parameters.
This task provides functions for defining, modifying, tracing, and extracting apertures from two dimensional spectra. The functions desired are selected using switch parameters. When the task is run interactively queries are made at each step allowing additional control of the operations performed on each input image.
The functions, in the order in which they are generally performed, are
summarized below.
Each of these functions has different options and parameters. In
addition to selecting any of these functions in this task, they may
also be selected using the aperture editor and as individual
commands (which themselves allow selection of other functions). When
broken down into individual tasks the parameters are also sorted by
their function though there are then some mutual parameter
interdependencies. This functional decomposition is what was available
prior to the addition of the apall task. It is recommended that
this task be used because it collects all the parameters in one
place eliminating confusion over where a particular parameter
is defined. However, documenting the various functions
is better organized in terms of the separate descriptions given for
each of the functions; namely under the help topics
apdefault, apfind, aprecenter, apresize, apedit,
aptrace, and apsum.
1. This example may be executed if desired. First we create an artificial
spectrum with four spectra and a background. After it is created you
can display or plot it. Next we define the dispersion axis and set the
verbose flag to better illustrate what is happening. The task APALL
is run with the default parameters except for background fitting and
subtracting added. The text beginning with # are comments of things to
try and do.
2. To extract a series of similar spectra noninteractively using a
reference for the aperture definitions, then recentering and resizing
but not retracing:
Note that the interactive flag automatically turns off the edit, fittrace,
and review options and the reference image eliminates the find
(find only occurs if there are no initial apertures).
As a final step when computing a weighted/cleaned spectrum the total
fluxes from the weighted spectrum and the simple unweighted spectrum
(excluding any deviant and saturated pixels) are computed and a
"bias" factor of the ratio of the two fluxes is multiplied into
the weighted spectrum and the sigma estimate. This makes the total
fluxes the same. In this version the bias factor is recorded in the logfile
if one is kept. Also a check is made for unusual bias factors.
If the two fluxes disagree by more than a factor of two a warning
is given on the standard output and the logfile with the individual
total fluxes as well as the bias factor. If the bias factor is
negative a warning is also given and no bias factor is applied.
In the previous version a negative (inverted) spectrum would result.
apdefault,
apfind,
aprecenter,
apresize,
apedit,
aptrace,
apsum,
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 aperture
editor.
o
Recenter reference apertures on the image spectrum profiles.
o
Resize the reference apertures based on spectrum profile width.
o
Interactively define or adjust aperture definitions using a graphical
interface called the aperture editor. All function may also
be performed from this editor and, so, provides an alternative
method of processing and extracting spectra.
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.
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.
EXAMPLES
ap> artdata
ar> unlearn artdata
ar> mk1dspec apdemo1d nl=50
ar> mk2dspec apdemo2d model=STDIN
apdemo1d 1. gauss 3 0 20 .01
apdemo1d .8 gauss 3 0 40 .01
apdemo1d .6 gauss 3 0 60 .01
apdemo1d .4 gauss 3 0 80 .01
[EOF=Control D or Control Z]
ar> mknoise apdemo2d background=100. rdnoise=3. poisson+
ar> bye
# Display or plot the spectrum
ap> dispaxis=2; verbose=yes
ap> unlearn apall
ap> apall apdemo2d back=fit
Searching aperture database ...
Find apertures for apdemo2d? (yes):
Finding apertures ...
Number of apertures to be found automatically (1): 4
Jul 31 16:55: FIND - 4 apertures found for apdemo2d.
Resize apertures for apdemo2d? (yes):
Resizing apertures ...
Jul 31 16:55: RESIZE - 4 apertures resized for apdemo2d.
Edit apertures for apdemo2d? (yes):
# Get a list of commands with '?'
# See all the parameters settings with :par
# Try deleting and marking a spectrum with 'd' and 'm'
# Look at the background fitting parameters with 'b' (exit with 'q')
# Exit with 'q'
Trace apertures for apdemo2d? (yes):
Fit traced positions for apdemo2d interactively? (yes):
Tracing apertures ...
Fit curve to aperture 1 of apdemo2d interactively (yes):
# You can use ICFIT commands to adjust the fit.
Fit curve to aperture 2 of apdemo2d interactively (yes): n
Fit curve to aperture 3 of apdemo2d interactively (no):
Fit curve to aperture 4 of apdemo2d interactively (no): y
Jul 31 16:56: TRACE - 4 apertures traced in apdemo2d.
Write apertures for apdemo2d to apdemosdb (yes):
Jul 31 16:56: DATABASE - 4 apertures for apdemo2d written to database.
Extract aperture spectra for apdemo2d? (yes):
Review extracted spectra from apdemo2d? (yes):
Extracting apertures ...
Review extracted spectrum for aperture 1 from apdemo2d? (yes):
# Type 'q' to quit
Jul 31 16:56: EXTRACT - Aperture 1 from apdemo2d --> apdemo2d.ms
Review extracted spectrum for aperture 2 from apdemo2d? (yes): N
Jul 31 16:56: EXTRACT - Aperture 2 from apdemo2d --> apdemo2d.ms
Jul 31 16:56: EXTRACT - Aperture 3 from apdemo2d --> apdemo2d.ms
Jul 31 16:57: EXTRACT - Aperture 4 from apdemo2d --> apdemo2d.ms
ap> apall fib*.imh ref=flat inter- trace-
REVISIONS
V2.11
The dispersion axis parameter was moved to purely a package parameter.
SEE ALSO
This page automatically generated from the iraf .hlp file. If you
would like your local iraf package .hlp files converted into HTML
please contact Dave Mills at NOAO.dmills@noao.edu