AIPS HELP file for AGAUS in 31DEC22
As of Tue Dec 5 2:00:15 2023
AGAUS: Fits 1-dimensional Gaussians to absorption-line spectra
INPUTS
INNAME Input image name (name)
INCLASS Input image name (class)
INSEQ 0.0 9999.0 Input image name (seq. #)
INDISK 0.0 9.0 Input image disk unit #
INVERS 0.0 XG table version number
OUTNAME Output image name (name)
OUTCLASS Output image name (class)
OUTSEQ -1.0 9999.0 Output image name (seq. #)
OUTDISK 0.0 9.0 Output image disk unit #.
BLC Bottom left corner of input
TRC Top right corner of input
YINC 0.0 128.0 Do every YINCth row in the
first pass
ZINC 0.0 128.0 Do every ZINCth plane in the
first pass
FLUX 0.0 Flux cutoff (see HELP)
ORDER 0.0 1.0 Order of baseline to fit
(always fits continuum)
DOOUTPUT -1.0 3.0 Write residual image: 1,3
write parameter img: 2,3
DOTV -1.0 2.0 Plot data on TV; 2 => use
TV not terminal for questions
DORESID -1.0 1.0 Plot residuals on TV if DOTV
DOMODEL -1.0 1.0 Plot individual components on
TV if > 1 and DOTV
PIXRANGE Min,Max of image intensity
Max <= Min => entire range
LTYPE -410.0 410.0 Type of labeling: 1 border,
2 no ticks, 3 standard, 4 rel
to center, 5 rel to subim cen
6 map pixels
PIXVAL 0.0 Display if peak < PIXVAL
NITER 0.0 4000.0 Max # fit iterations
0 -> 100.
NGAUSS 1.0 8.0 Number of Gaussians (<= 8)
Guess of model parameters
RMSLIMIT Switch from automatic to
interactive if rms > RMSLIMIT
BADDISK Disk to avoid for scratch
HELP SECTION
AGAUS
Task: Fits one-dimensional Gaussians to each row of an image,
normally transposed spectra-line images. This is a special
version of XGAUS designed to fit absorption-line spectra with
Gaussians in optical depth. As such it requires that the image
contain the continuum values rather than being produced by
a continuum subtraction either before or after imaging.
The task fits up to 8 Gaussians plus a linear baseline
to each row. Optionally, it writes up to 4 + 8*NGAUSS n-1
dimensional images containing the fit parameters and their
uncertainties and/or the residual image. With a careful choice
of input parameters, the task is capable of running in a
batch-like mode. However, particularly for NGAUSS > 1, an
interactive mode (using the TV graphics planes) is recommended.
Interactivity is requested by setting DOTV greater than zero.
Note that, since the TV is not allowed in BATCH jobs, AGAUS
turns off all interactive options and TV displays when it is
run in batch.
The TV will let color differentiate what is plotted: DOTV > 0
(plot data, allow initial guesses to be set AND see what was
fit). The initial guess uses a DC level and slope of 0 so it
will help if serious baselines are removed prior to AGAUS.
The initial gues is plotted as X signs. The data are plotted
with stepped connecting lines, the fit as a smooth connecting
line, and the residual as a dashed line. The guess is in
graphics channel 2 (usually green), the data in 1 (usually
yellow), the fit in 4 (usually cyan), and the residual in 3
(usually pink).
When AGAUS is run in interactive mode, no output files are
created except for a large table file used to hold the results
of the fitting (an XG file). The table is initialized with
pixel positions and fluxes before any fitting is done. Then
the fitting is done sequentially through the input cube in two
passes. The first pass does every YINC'th row and ZINC'th
plane, while the second pass does every pixel not already done.
After that, in interactive mode, a menu-driven routine is
brought up to allow you to review the fits including re-doing
poor ones, rearranging the numbering of the components, and
other editing of the results. Finally output files are written
if requested or if the task has been run in a non-interactive
mode. Note that the line center is an offset with respect to
the reference channel, not the channel number itself.
AGAUS may be re-started using the XG file either resuming the
sequential fitting (if it was not completed) or dropping into
the edit stage directly. The XG file is created over all
pixels in the input images. Therefore, you may use a small
range for BLC(2) - TRC(2) and BLC(3) - TRC(3) to do a small
region of the source. You may then re-start using another
small range in Y and Z covering another particular region of
similar line shapes. The output images will cover the entire
range of the input images. When doing this, it is a good idea
not to change BLC and TRC (1,4,5,6,7). Note too that the
various sessions are allowed to use different values of NGAUS.
The table routines always handle 8 Gaussians, but it is much
easier to provide guesses for a small number of Gaussians whose
values will be then stored in the low numbered Gaussians. In
the edit stage, you could specify a large number of Gaussians
and move some of these low numbered solutions into higher
numbers if appropriate.
Details of the interactive operation and options are described
in the EXPLAIN file. See also AIPS Memo 118, "Modeling
spectral cubes in AIPS", January 2016 for a more detailed
description of the use of this task.
Adverbs:
INNAME.....Input image name (name). Standard defaults.
INCLASS....Input image name (class). Standard defaults.
INSEQ......Input image name (seq. #). 0 => highest.
INDISK.....Disk drive # of input image. 0 => any.
INVERS.....Input XG table version. 0 => a new one. Set this adverb
if you wish to re-start a fitting session.
OUTNAME....Output image name (name). Standard defaults.
OUTCLASS...Output image name (class). Standard defaults.
Used only for the residual image. The OUTCLASSes for the
fit parameters are SLOPE, CONST, AMPLn, CENTRn, and
WIDTHn and for the uncertainties are DSLOPE, DCONST,
DAMPLn, DCENTn, and DWIDTn. The "flux" of each component
(ampl * width * 1.06) is written with OUTCLASSes of FLUXn
and DFLUXn.
OUTSEQ.....Output image name (seq. #). 0 => highest unique.
OUTDISK....Disk drive # of output image. 0 => highest number with
sufficient space.
BLC........Bottom right corner in input image of desired subimage.
Default is entire image. The XG table always uses the
full size of the 2nd and 3rd axes of the input image.
The fitting in this pass is restricted to the BLC/TRC
range in spectral channels and the 2 spatial axes.
If you are restarting using an existing XG table, you may
set BLC/TRC to values different than when the XG table
was created. This allows different ORDER, NGAUS, etc in
different regions of your image cube.
TRC........Top right corner in input image of desired subimage to be
used in fitting. Default is entire image.
YINC.......Do only every YINC'th row (beginning at BLC(2)) in the
first pass. Do the other rows in the second pass.
ZINC.......Do only every ZINC'th plane (beginning at BLC(3)) in the
first pass. Do the other planes in the second pass.
FLUX.......A flux cutoff in the same units as the input image (i.e.
Jy/beam). If a row does not have three consecutive
points above this level, no component is fit to the row.
It is also used to limit the points which determine the
initial guess. If you do a re-start with a new lower
value of FLUX, AGAUS will go into a special sequential
mode to fit all rows with values between the previous and
new FLUX levels.
ORDER......The order of the baseline to fit: -1 none, 0 DC level
only, 1 DC level and slope.
DOOUTPUT...= 1 or 3 requests that the residual (data-model) image
be written out as a cataloged image using
OUTCLASS.
= 2 or 3 requests that the model images be written out
as cataloged images.
Note that DOOUTPUT can be changed interactively during
the imaging portion of the task and the value of the
adverb at exit is all that matters.
DOTV.......True (> 0) implies plot the data, the initial guess, and
the fit model on the TV. It must be set > 0. if you wish
the option to correct initial guesses with the TV
cursor. If DOTV > 0 and NGAUSS > 1, the program pauses
after plotting its initial guess and requests user input
from a TV menu (DOTV=2) or the terminal. Click DO_FIT
(hit Enter key on terminal) to proceed with the program's
initial guess. Enter BAD to have the solution for the
row blanked or QUIT to exit the task directly. Click
RE-GUESS (E or e on the terminal) to have the program
request your guidance as to a better initial guess.
During the entering of a new initial guess with the TV
cursor, you may request that a particular component be
null (held at 0 amplitude) by indicating that its peak or
half-width point is outside the plot area.
DORESID....True (> 0) requests a plot of the final residual values
in each row. Note that the plot scale is set by the data
and so may not cover any of the residual values.
If DOTV is true, the program will pause after each row
and request input from a TV menu (DOTV=2) or the
terminal. At that point, click GOOD (Enter key on the
terminal) to keep the answer (for now). You may enter
BAD to have the solution blanked. The program will warn
you if any of the fit parameters are way out of normal
limits. For NGAUSS > 1, one may also enter RETR to loop
back and try again with a manually entered initial
guess.
DOMODEL....True (> 0) requests a plot of the individual Gaussians
fit when there is more than one. The plot is in graphics
plane 7 (reddish-yellow) unless DORESID is false, in
which case the plot is in plane 3 (pink) which is usually
used for the residuals.
PIXRANGE...Min,Max of Image intensity. 0,0 => min,max of EACH
row (separately).
LTYPE......Labelling type, see HELP LTYPE for details:
1 = border, 2 = no ticks, 3 or 7 = standard, 4 or 8 =
relative to ref. pixel, 5 or 9 = relative to subimage
(BLC, TRC) center, 6 or 10 = pixels. 7-10 all labels
other than tick numbers and axis type are omitted.
Less than 0 is the same except that the plot file
version number and create time are omitted.
Add n * 100 to alter the metric scaling.
PIXVAL.....Plot row only if the peak value < PIXVAL. Limits the
plots to those of uncertain intensities. 0 -> 10^9.
NITER......Maximum function evaluations during the fit of each row.
(< 10 -> 100 for NGAUSS > 1, < 100 -> 150 for 1
Gaussian)
NGAUSS.....Number of Gaussians to fit (between 1 and 8).
RMSLIMIT...When the fitting has been told to continue without the
TV, switch interactive mode back on whenever the
residual rms exceeds RMSLIMIT. 0 -> 1000000.
BADDISK....Disk drives to avoid for scratch files.
EXPLAIN SECTION
IMAGR: One-dimensional Gaussian fitting of image cubes
Documenter: E. W. Greisen NRAO
Related Programs: CUBIT, GAL, IMFIT, JMFIT, SAD, SLFIT
AGAUS is a version of XGAUS which fits Gaussians to absorption spectra
using the model that the optical depth is a sum of Gaussians. At
present, AGAUS assumes that there are at most 3 axes with more than
one pixel in the input image.
AGAUS begins by making an XG table containing one row for every pixel
in the output plane from BLC(2,3) to TRC(2,3). Each row of the table
is initialized with the peak value in each row of the input image,
where the "peak" is the largest value averaged over 3 adjacent pixels.
Then AGAUS begins fitting those rows having a peak value above FLUX,
doing every YINC pixel in the Y axis and ZINC pixel in the Z axis.
Initial guesses for each fit are found from the row data when NGAUSS =
1 or from a previous fit for NGAUSS > 1. This is one of the reasons
the interactive mode is recommended strongly for NGAUSS > 1. After
each input image row is fit, the results are added to the XG table
immediately. This allows the interactive user to quit at any time and
then restart the process later (set INVERS to point at the
pre-existing XG table which you intend to modify). After the YINC by
ZINC pass through the data, a second pass through the data is done on
every pixel. Those pixels which have already been fit are skipped,
but the results from them contribute to the next initial guess.
Finally, when all pixels have been fit, AGAUS enters an interactive
routine designed to improve the results before any output images are
written. However, before describing that function, we need to provide
details of the interactive fitting of each row of the input image.
This process is followed whenever a row is fit in the first YINC/ZINC
function, in the second every pixel function, and in the third result
editing function.
For each row, the first step in the fitting process is to determine an
initial guess non-interactively. If AGAUS is currently in interactive
mode, the next steps are:
1. If DOTV > 0 (STRONGLY recommended), the input data are plotted
on the TV and the initial guess is added to the plot of the
data.
2. If DOTV > 0 and either NGAUSS > 1 or a fitting has been forced,
AGAUS asks in the AIPS window for instructions using a TV menu
(DOTV=2) or the terminal input window. If your answer begins
with E or e (RE-GUESS on the TV), AGAUS will ask you to enter a
new initial guess (step 3). If the answer begins with B or b
(BAD on the TV), AGAUS will mark this pixel as bad and, if the
answer begins Q or q (QUIT on the TV), AGAUS will simply exit,
allowing you to restart it at a later time. If the answer is
anything else, e.g. a simple carriage return ("Enter") or GOOD
on the TV, AGAUS goes on to step 4 below.
3. To enter a new initial guess, you will be prompted to position
the TV cursor at the center and height of each Gaussian (note
that the X and Y positions matter) and at the half-width of each
Gaussian (note that only the X position matters). To mark each
point, hit any button (A, B, C, or D). AGAUS then returns to
step 1 above to plot the new guess and ask again.
4. Once an acceptable initial guess has been found, AGAUS proceeds
to call a non-linear least squares fitting routine to determine
the Gaussian parameters that appear to fit the data best. the
answers are then checked to see if they are "reasonable" -
negative components, components centered outside the input
data, and components < 1.5 cells wide (FWHM) are thought to be
unreasonable.
5. If the result is unreasonable and the current mode is not
interactive, but it started as interactive, the interactive
mode is turned back on (with a message and a display of the
answers in the message terminal window) and AGAUS returns to
step 1. If the task did not start as interactive and the
result is unreasonable, the solution for that input row is
marked bad and the task goes on to the next row.
6. If the current mode is interactive, the final model is added to
the plot (cyan color), residuals are added to the plot (pink
color and only if DORESID > 0) and the final model components
are also added to the plot (reddish-yellow or pink if DORESID
<= 0, but only if DOMODL > 0). In the input terminal, you are
then told if the answers are "unreasonable" and are shown the
answers, reasonable or not. You are then offered a variety of
choices. If your response begins with:
a) B or b - the solution is marked as bad and AGAUS goes on
to the next input row (BAD on the TV)
b) Q or q - AGAUS exits cleanly, leaving the XG table to be
worked on again at a later time (QUIT on the
TV).
c) R or r - AGAUS returns to step 1 to try again with the
current number of Gaussians (<= NGAUSS)
(RE-GUESS on the TV).
c) E or e - AGAUS returns to step 1 to try again with the
current number of Gaussians (<= NGAUSS)
(RE-GUESS on the TV).
e) 1, 2, 3, 4, 5, 6, 7, 8 - AGAUS returns to step 1 to try
again with the specified number of Gaussians
(note that only numbers <= NGAUSS are respected)
(1, 2, 3, 4, 5, 6, 7, and 8 on the TV as needed)
f) H or h - AGAUS prompts you to enter the Gaussian
parameters for each component (HAND on the TV).
You enter the peak in input image units, the
center in pixels wrt the reference pixel, and
width in pixels. All 3 numbers must appear in
one line. You may also put in flags to control
whether your hand-entered numbers may be changed
if the spectrum is re-fit. Values > 0 mean that
the parameters will be fit, and all omited flags
are taken as 1. It will prompt for all NGAUSS
components, but will change the prompt if the
current number of Gaussians is < NGAUSS. If you
enter something besides 0 in that case, the
current number of Gaussians is increased
appropriately. AGAUS then returns to the start
of this step 6 to allow you to see if you made a
good guess.
g) D or d - After a HAND operation, a DO FIT option is
available. It loops back using the hand-entered
parameters as the initial guess to the fitting
routine.
h) T or t - AGAUS turns off the interactive mode and does
solutions in a batch-like fashion until an
unreasonable solution is found or it finishes
the current function. (TVOFF on the TV)
i) Anything else - AGAUS saves the answer (with
uncertainties) and goes on to the next input
row (GOOD on the TV)
Note, on retries (R, E, 1, 2, 3, and 4), step 2 will skip the
questions and go on to step 3 directly (as if you had answered
E).
Recommended adverb values are DOTV = 2 and probably DORESID = 1. This
allows full information and interactivity and uses different graphics
planes for the different plots. DOTV = 2 will save moving back and
forth between the TV and the terminal all the time.
After all pixels that are strong enough have been given a solution,
AGAUS enters a menu-driven function. The menu has in the left column:
| EXIT | Exit AGAUS, writing output images if DOOUTPUT is
now > 0.
| SET MIN S/N | Set minimum amplitude S/N(s) for okay solutions
| SET MAX RES | Set maximum residual for okay solutions
| SET PEAK RANGE | Set peak value range(s) for okay solutions
| SET CENTER RANGE| Set X center range(s) for okay solutions
| SET WIDTH RANGE | Set width range(s) for okay solutions
| SET MAX ERR WID | Set maximum error(s) in width for okay solutions
| REDO ALL | Re-do all solutions which are not okay
| FLAG ALL | Mark bad all solutions which are not okay
| OFF ZOOM | Turn of TV zoom
| OFF TRANSFER | Turn off black & white and color TV enhancements
| RESET WINDOW | Display full view of current image
| LABEL WEDGE? | Turn on/off labeling of step wedge
| SET DOOUTPUT | Increment DOOUTPUT in loop 0-3 - with 1 and 3
causing residual images and 2 and 3 causing
parameter images to be written on EXIT
| ADD TO LIST | Type in output pixel coordinates to add to list
| SHOW LIST | Display coordinates in list
| REDO LIST | Re-do solutions for all pixels in list
| FLAG LIST | Flag solutions for all pixels in list
| SWAP LIST 1-2 | Swap solutions for components 1 and 2 for all
pixels in list
| SWAP LIST 1-3 | Swap solutions for components 1 and 3 for all
pixels in list
| SWAP LIST 2-3 | Swap solutions for components 2 and 3 for all
pixels in list
| SWAP LIST 1-4 | Swap solutions for components 1 and 4 for all
pixels in list
| SWAP LIST 2-4 | Swap solutions for components 2 and 4 for all
pixels in list
| SWAP LIST 3-4 | Swap solutions for components 3 and 4 for all
pixels in list
Only appropriate SWAP LIST options are actually displayed.
Three editing concepts are present in this menu. The first is to
establish what parameter values (S/N in peak, peak residual, peak
values, center values, width values, and error in widths) for each
component constitute an "okay" solution. The selected limits are
displayed above the menu. Then you can choose to try to REDO ALL
solutions which are not okay or simply FLAG ALL, marking them as bad.
The second concept is to create a list of up to 1000 pixels which are
thought to have some problem. You can enter these pixels by hand (or
remove pixels from the list by hand) with ADD TO LIST. A faster way
to add to the list is to show the image of some parameter and then
select interesting pixels while doing CURVALUE (see below). The list
of pixels can be re-done (REDO LIST) or marked as bad (FLAG LIST).
The list is cleared by these operations so you can make a new list as
needed. The third editing method available here is to take the pixel
list and swap the solutions at those pixels between component N with
component M.
The right hand column of options include:
| SHOW IMAGE A1 | Enter image interaction with peak value of
component 1
| SHOW IMAGE C1 | Enter image interaction with center pixel of
component 1
| SHOW IMAGE W1 | Enter image interaction with width of
component 1
| SHOW IMAGE F1 | Enter image interaction with "flux" of
component 1
| SHOW IMAGE EA1 | Enter image interaction with uncertainty in
peak value of component 1
| SHOW IMAGE EC1 | Enter image interaction with uncertainty in
center pixel of component 1
| SHOW IMAGE EW1 | Enter image interaction with uncertainty in
width of component 1
| SHOW IMAGE EF1 | Enter image interaction with uncertainty in
"flux" of component 1
For NGAUSS > 1, appropriate additional choices are offered.
For NGAUSS > 4, additional columns are needed in the menu.
When you select one of the above options, the above menus are turned
off, the image plane maintained in memory is displayed on the TV
screen, and a new menu is displayed. If offers:
| RETURN | Return to the above menus, image stays displayed
| LOAD AS SQ | Re-load image with square root transfer function
| LOAD AS LG | Re-load image with log transfer function
| LOAD AS L2 | Re-load image with extreme log transfer function
| LOAD AS LN | Re-load image with linear transfer function
| SET WINDOW | Set a sub-image to view
| RESET WINDOW | Return to viewing the full image
| OFF TRANSF | Turn off enhancement done with TVTRANSF
| OFF COLOR | Turn off color enhancements
| TVTRANSF | Black & white image enhancement
| TVPSEUDO | Color enhancement of numerous sorts
| TVPHLAME | Color enhancement of flame type, multiple colors
| TVZOOM | Interactive zooming and centering of image
| CURVALUE | Display value under cursor, mark pixels for list
| SWAP 1-2 | Swap solutions for components 1 and 2 interactively
| SWAP 1-3 | Swap solutions for components 1 and 3 interactively
| SWAP 2-3 | Swap solutions for components 2 and 3 interactively
| SWAP 1-4 | Swap solutions for components 1 and 4 interactively
| SWAP 2-4 | Swap solutions for components 2 and 4 interactively
| SWAP 3-4 | Swap solutions for components 3 and 4 interactively
| NEXT WINDOW | Move to next window into large images
For NGAUSS < 4, appropriate SWAP options are suppressed.
Only one of the LOAD AS xx options is offered - SQ when the current
function type is LN, LG when the current function type is SQ, L2 when
the current function type is LG, and LN when the current type is L2.
Selecting this option, reloads the image with the newly selection
function type and changes the menu option accordingly. The options
OFF TRANSF through TVZOOM are essentially the same as the
corresponding verbs in AIPS. CURVALUE is like the verb of that name,
but, when you press buttons A or B, the pixel under the cursor is
added to the editing list.
The SWAP n-m options invoke the interactive polygon setting operation
used by the AIPS verb TVSTAT. This starts in the "set polygon n" mode
where button A selects a vertex in the polygon, B sets the last vertex
in the polygon and gets ready to set polygon n+1, C sets the last
vertex and enters a vertex editing mode, and D sets the last vertex
and exits the polygon setting. In the vertex editing mode, move the
cursor to a vertex to be moved and press button A or B to reset its
position. After moving it to the desired point, press button A or B
to fix that point and restart the vertex editing mode. Press button C
to fix that point and then start creating polygon n+1. Press button D
to fix that point and exit the polygon setting. Once button D has
been set, the selected areas of pixels have their solutions swapped.
The images are updated and reloaded automatically.
Very large images may not be able to fit on your TV. When the image
exceeds the size of the TV, the top line will show the component
number followed by a subimage number in parentheses and the NEXT
WINDOW option will appear. The first sub-image displayed is called
number 0 and shows the full image every n'th pixel in X and Y.
Sub-image 1 begins at the lower left, moves right, then back to the
left and up, and so forth until the top right is reached. Every pixel
is displayed in these sub-images. Use the NEXT WINDOW option to step
through the sub-images in a circular fashion.