%;----------------------------------------------------------------------
%;  Copyright (C) 2017, 2020, 2025
%;  Associated Universities, Inc. Washington DC, USA.
%;
%;  This program is free software; you can redistribute it and/or
%;  modify it under the terms of the GNU General Public License as
%;  published by the Free Software Foundation; either version 2 of
%;  the License, or (at your option) any later version.
%;
%;  This program is distributed in the hope that it will be useful,
%;  but WITHOUT ANY WARRANTY; without even the implied warranty of
%;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%;  GNU General Public License for more details.
%;
%;  You should have received a copy of the GNU General Public
%;  License along with this program; if not, write to the Free
%;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
%;  MA 02139, USA.
%;
%;  Correspondence concerning AIPS should be addressed as follows:
%;          Internet email: aipsmail@nrao.edu.
%;          Postal address: AIPS Project Office
%;                          National Radio Astronomy Observatory
%;                          520 Edgemont Road
%;                          Charlottesville, VA 22903-2475 USA
%-----------------------------------------------------------------------
\documentclass[twoside]{article}
\usepackage{palatino}
\renewcommand{\ttdefault}{cmtt}
% Highlight new text.
\usepackage{color}
\usepackage{alltt}
\usepackage{graphicx,xspace,wrapfig}
\usepackage{pstricks}  % added by Greisen
\definecolor{hicol}{rgb}{0.7,0.1,0.1}
\definecolor{mecol}{rgb}{0.2,0.2,0.8}
\definecolor{excol}{rgb}{0.1,0.4,0.1}
\newcommand{\Hi}[1]{\textcolor{hicol}{#1}}
%\newcommand{\Hi}[1]{\textcolor{black}{#1}}
\newcommand{\Me}[1]{\textcolor{mecol}{#1}}
%\newcommand{\Me}[1]{\textcolor{black}{#1}}
\newcommand{\Ex}[1]{\textcolor{excol}{#1}}
%\newcommand{\Ex}[1]{\textcolor{black}{#1}}
\newcommand{\No}[1]{\textcolor{black}{#1}}
\newcommand{\hicol}{\color{hicol}}
%\newcommand{\hicol}{\color{black}}
\newcommand{\mecol}{\color{mecol}}
%\newcommand{\mecol}{\color{black}}
\newcommand{\excol}{\color{excol}}
%\newcommand{\excol}{\color{black}}
\newcommand{\hblack}{\color{black}}
%
\newcommand{\AIPS}{{$\cal AIPS\/$}}
\newcommand{\eg}{{\it e.g.},}
\newcommand{\ie}{{\it i.e.},}
\newcommand{\etal}{{\it et al.}}
\newcommand{\tablerowgapbefore}{-1ex}
\newcommand{\tablerowgapafter}{1ex}
\newcommand{\keyw}[1]{\hbox{{\tt #1}}}
\newcommand{\sub}[1]{_\mathrm{#1}}
\newcommand{\degr}{^{\circ}}
\newcommand{\vv}{v}
%\newcommand{\vv}{\varv}
\newcommand{\eq}{\hbox{\hspace{0.6em}=\hspace{0.6em}}}
\newcommand{\newfig}[2]{\includegraphics[width=#1]{data.fig#2}}
%\newcommand{\putfig}[1]{\includegraphics{data.fig#1.eps}}
\newcommand{\putfig}[1]{\includegraphics{#1.eps}}
\newcommand{\whatmem}{\AIPS\ Memo \memnum}
\newcommand{\boxit}[3]{\vbox{\hrule height#1\hbox{\vrule width#1\kern#2%
\vbox{\kern#2{#3}\kern#2}\kern#2\vrule width#1}\hrule height#1}}
%
\newcommand{\memnum}{122 \Hi{Revised}}
\newcommand{\memtit}{Modeling Absorption-line Cubes in \AIPS}
\title{
   \vskip -35pt
   \fbox{{\large\whatmem}} \\
   \vskip 28pt
%   \vskip 10pt
%   \fbox{{\Huge \Me{D R A F T}}}
%   \vskip 10pt
   \memtit \\}
\author{Eric W. Greisen}
%
\parskip 4mm
\linewidth 6.5in                     % was 6.5
\textwidth 6.5in                     % text width excluding margin 6.5
\textheight 9.0 in                  % was 8.81
\marginparsep 0in
\oddsidemargin .25in                 % EWG from -.25
\evensidemargin -.25in
\topmargin -0.4in
%\topmargin 0.2in
\headsep 0.25in
\headheight 0.25in
\parindent 0in
\newcommand{\normalstyle}{\baselineskip 4mm \parskip 2mm \normalsize}
\newcommand{\tablestyle}{\baselineskip 2mm \parskip 1mm \small }
%
%
\begin{document}

\pagestyle{myheadings}
\thispagestyle{empty}

\newcommand{\Rheading}{\whatmem \hfill \memtit \hfill Page~~}
\newcommand{\Lheading}{~~Page \hfill \memtit \hfill \whatmem}
\markboth{\Lheading}{\Rheading}
%
\vskip -.5cm
\pretolerance 10000
\listparindent 0cm
\labelsep 0cm
%
%

\vskip -30pt
\maketitle

\normalstyle
\begin{abstract}
  \AIPS\ does Gaussian fitting of spectral lines with overhauled task
  \keyw{XGAUS} and can fit V polarization image cubes for Zeeman
  splitting with the task \keyw{ZEMAN}\@.  Both of these tasks are
  designed for emission spectra in which the noise is not a function of
  spectral channel.  In absorption, however, the noise in optical depth
  becomes high when the optical depth is high.  Therefore, new tasks
  \keyw{AGAUS} and \keyw{ZAMAN} have been written to provide similar
  functions but with mathematics suitable for absorption lines.  This
  memo describes the new tasks in some detail and includes a description
  of a new, simplified modeling task \keyw{MODAB} which may also be
  useful.  That task has shown that the results of these four tasks are
  biased by the presence of the Zeeman splitting and need modest
  correction if they are meant to describe the actual pre-splitting line
  widths and magnetic field.  \footnote{Color is used to indicate
    changes made to this document: \Hi{for the April, June and
      September, 2025 revisions}.}

\end{abstract}

\renewcommand{\floatpagefraction}{0.75}
\typeout{bottomnumber = \arabic{bottomnumber} \bottomfraction}
\typeout{topnumber = \arabic{topnumber} \topfraction}
\typeout{totalnumber = \arabic{totalnumber} \textfraction\ \floatpagefraction}

\section{Introduction}

{\tt XGAUS} was written a long time ago in the hopes that converting a
spectral cube, with many spectral channels at each spatial location,
into one or more sets of images of peak, center, width, and integral
would simplify the data presentation.  One could even hope that the
separate Gaussians fit might have some separate physical reality.
{\tt XGAUS} was extensively re-written beginning in 2013 and is now a
quite friendly and powerful task.  Accompanying this task is {\tt
  ZEMAN} which first appeared in 2013 and which solves for Zeeman
splitting of the right and left polarizations using a new Gaussian
model or the older methods involving the derivative of the unpolarized
spectra.  These tasks are described in detail in \AIPS\ Memo 118
(revised)\footnote{Greisen, Eric W., 2013 \Hi{2025}, ``Modeling Spectral
  Cubes in \AIPS'', AIPS Memo 118, NRAO, Socorro, NM.}

However, these tasks are designed for emission lines for which the noise
is not a significant function of spectral channel.  In absorption, the
optical depth is the physical parameter which one might expect to be
Gaussian.  However, the noise in optical depth is a significant function
of spectral channel whenever the optical depths become large.  This
calls for a new fitting routine to use Gaussian models in optical depth,
but to fit the actual spectra for which the noise is approximately
independent of spectral channel.  This new task is named {\tt AGAUS} and
is very similar to {\tt XGAUS}, but with enough differences that
combining the two functions in one task is impractical.

A revision of {\tt ZEMAN}, called {\tt ZAMAN}, has also been written
to solve for Zeeman splitting using the appropriate mathematics for
absorption-line Gaussians.  That mathematics will be presented below
in some detail.  A simple modeling task was written to prepare image
cubes of known properties in order to test these new tasks.  It has
made it clear that the answers from {\tt XGAUS} and {\tt AGAUS} are
affected by the Zeeman splitting as are the answers from {\tt ZEMAN}
and {\tt ZAMAN}\@.  The nature of the bias in the answers will be
discussed below and correction methods suggested.

\section{Absorption-line Gaussian fitting: {\tt AGAUS}}

In absorption, we assume that the optical depth is proportional to the
number of atoms/molecules in the line of sight and that the radial
velocities of these absorbers is approximately Gaussian.  Thus the
function we seek to fit is
\begin{equation}
   T(x,y,z) = (A(y,z) + B(y,z) * x) \times \exp (-\tau(x,y,z))
\end{equation}
where
\begin{equation}
   \tau(x,y,z) = \sum_1^{\tt NGAUSS} \tau_i e^{-\alpha (x - x_i)^2 /
     \sigma_i^2}
\end{equation}
where $x$ is the coordinate along the first axis of the image cube,
$A(y,z) + B(y,z)x$ is the spectral baseline (the continuum),
$\tau_i(y,z)$ are the peak optical depths of each of the {\tt NGAUSS}
components, $x_i(y,z)$ are the center channels of the components,
$\sigma_i(y,z)$  are the full widths at half maximum of the components
and $\alpha = 4 \ln(2)$ to impart this meaning to the $\sigma_i$.

{\tt AGAUS} will fit this formulation to every row of a Stokes I image
cube.  Note that this cube must contain the full continuum emission of
the source ($A(y,z)$) in order to be described by these equations.  It
then produces images over the second and third input axes of the fit
parameters.  Normal usage has the first axis of the cube as a spectral
axis, either in frequency or velocity units, and the second and third
axes are celestial coordinates.  This usage will be assumed in the
later discussion.

\subsection{Inputs}

The usual {\tt INNAME} {\it et al.} adverbs define the cube to be fit
and the {\tt OUTNAME} {\it et al.} adverbs define the (eventual)
output name.  The {\tt INVERS} adverb controls which {\tt XG} table is
used by the task, with $\leq 0$ meaning a new table.  {\tt BLC} and
{\tt TRC} define the pixel ranges to be used in the current execution,
where {\tt BLC(1)} and {\tt TRC(1)} control the spectral channels that
will be fit and {\tt BLC(2)}, {\tt TRC(2)}, {\tt BLC(3)}, and {\tt
TRC(3)} control the area in celestial coordinates over which the
fitting is done.  New {\tt XG} table files are created for the entire
input image cube, but are filled with peak brightnesses limited by {\tt
  BLC(1)} through {\tt TRC(1)}\@.  Therefore, it would be wise to use as
much of the first axis as is reliable when creating a new table.  The
second and third values of these adverbs then limit the area over which
fitting is done during this execution of {\tt AGAUS}\@.  Adverbs {\tt
  YINC} and {\tt ZINC} control the stride taken in the first pass
through the cube; a second pass will then fit all voxels not fit in the
first pass.  {\tt FLUX} controls which spectra will be fit during this
execution; all positions with 3 consecutive channels averaging above
{\tt FLUX} will be fit.  The initial guess for the linear baseline
(continuum brightness) is taken as the peak value with no slope.  {\tt
  ORDER} controls the order of the baseline with $\leq 0$ meaning a
constant and $\ge 1$ meaning a constant plus a slope.  {\tt DOOUTPUT}
controls what files are written --- this may be changed interactively
\Hi{(except for one-dimensional images)} so leave it zero at this point.
Set \Hi{{\tt DOTV = 1}} to use the task interactively.  Even when
fitting only 1 Gaussian component, it is best to watch what is happening
so you should never set this adverb false.  {\tt DORESID} controls
whether residuals are plotted on the fit spectra.  Such plots often
provide clues when more Gaussians are needed for the best fits.
However, the plots are self-scaled from the data only and so may not
include the residuals which should be near zero.  Set {\tt PIXRANGE} if
you must see the residuals.  In general it is best to set {\tt PIXRANGE}
to zero to see the full range of image values in best detail, but, if
you are fitting weak Gaussians in the presence of very strong ones, you
might wish to cut off the lowest values.  This will not interfere with
setting initial guesses as the plot of apparent optical depth is always
self-scaled.  \Hi{Note that, in {\tt 31DEC25}, {\tt PIXRANGE} may be set
  interactively so its value at this point is not important.} Set {\tt
  LTYPE} to your favorite type of labeling, set {\tt PIXVAL} to zero to
see all positions being fit, and leave {\tt NITER} zero since 100 is
more than enough iterations. Set {\tt NGAUSS} to the number of Gaussians
to be fit in this execution.  \Hi{If a new {\tt XG} table is created,
  {\tt NGAUSS} sets the maximum number of components that may appear in
  that table. In {\tt 31DEC25}, {\tt NGAUSS} may be as large as 32,
  while previous versions limited {\tt NGAUSS} to 8 and always set the
  maximum in the table to eight. {\tt NGAUSS} may be changed if you
  re-start on a pre-existing {\tt XG} table but only with less than or
  equal that original number of Gaussians.  A task to get around this
  limitation has also appeared in {\tt 31DEC25}\@.  {\tt XG2XG} IS
  discussed in \AIPS\ Memo 118.}  {\tt RMSLIMIT} is an upper limit for
the rms of a fit before the fit is viewed as ``failed'' which causes the
TV and interaction to be turned back on after you have turned it off.
You should get a good idea of an appropriate value from your initial
uses of {\tt AGAUS} or from your knowledge of the noise in your data
cube.

Just as in {\tt XGAUS}, {\tt AGAUS} begins by creating an {\tt XG}
table and populating each row with the largest average brightness over
three consecutive channels in the corresponding row in the range {\tt
  BLC(1)} through {\tt TRC(1)}\@..  Then it reads the table every {\tt
  YINC} rows and {\tt ZINC} planes and, for those with an average
brightness greater than {\tt FLUX}, attempts a fit.  Your interaction
with this fit will be described below.  After the first pass, the task
loops over every row and plane fitting those positions which have
enough brightness and which have not already been fit.  Finally, after
all voxels above {\tt FLUX} have been fit, the task goes into an
``edit'' mode.  It constructs images of each fit parameter and the
integral flux of the Gaussian, and of the uncertainties in these
parameters.  \Hi{In {\tt 31DEC25}, it also constructs an image of the
  rms over the $x$ axis for every $(y,z)$ pixel.  This image has a value
  at every pixel unlike the parameter images which have non-blanked
  values only at the pixels where the fit was regarded as good.}  You
may view these images, select positions explicitly or by their parameter
values or rms and revisit the fits of those positions.  This stage will
be described in detail below.

At any time you may exit the task and then re-start it using the same
{\tt XG} table.  Good reasons for doing this include fitting smaller
regions with each pass using the appropriate number of Gaussians for
that region.  Doing small regions which will have similar parameter
values helps a great deal with the initial guessing done by the task
(mostly using the previous solution).  You might also fit the cube
initially with a high value of {\tt FLUX} and then re-start with a lower
value to extend the areas fit.

\subsection{Fitting}

\begin{figure}
\begin{center}
\resizebox{6.0in}{!}{\putfig{AGAUS.a}}
\centerline{\hphantom{MM}}
\resizebox{6.0in}{!}{\putfig{AGAUS.b}}
\caption{\Hi{Top: First spectrum to fit, initial ``guess'' is all zero
    so {\tt RE-GUESS} will be selected.  Bottom: First spectrum to fit:
    optical depth spectrum to mark the Gaussians.  Note the change to an
    optical depth spectrum with a changed color to indicate that a guess
    is needed.}}
\label{fig:AGAUS.init}
\label{fig:AGAUS.guess}
\end{center}
\end{figure}


The fitting process starts with a plot of the spectrum with the data
and axis labels in graphics channel one (usually yellow) and the
initial guess as X's in graphics channel two (usually green).  Then
you are offered a menu of options on the TV (XAS window).  \Hi{We use a
simplified source model in all figures for clarity.  The model is the
sum of two models computed by {\tt MODAB}\@.}   The first spectrum to be
fit is illustrated in Figure~\ref{fig:AGAUS.init} at the top showing
that the first guess for more than one Gaussian is not useful.  The menu
that appears at this point is\\

\begin{center}
  \hicol
\begin{tabular}{|l|l|}\hline
   {\tt DO FIT}   & Attempt a fit \\
   {\tt RE-GUESS} & Interactively enter a new initial guess \\
   {\tt BAD}      & Mark pixel bad and go on \\
   {\tt QUIT}     & Exit {\tt AGAUS} now \\ \hline
\end{tabular}
\end{center}
\hblack

You select a menu option by moving the cursor to the desired option
with the mouse and registering that move with the TV by clicking the
left mouse button.  The selected menu item will change color as shown
in the figure.  If you press TV ``button'' {\tt D} at this point
(actually keyboard character D), helpful information about the
selected item will appear in your terminal window.  If you press one
of TV ``buttons'' {\tt A}, {\tt B}, or {\tt C} (actually keyboard
characters A, B, C), the selected function will be performed.  The
option to {\tt QUIT} causes the task to quit at this point.  You may
re-start later.  The option {\tt BAD} will mark this position as failed
and go on to the next position.  The option {\tt DO FIT} will cause the
task to attempt the non-linear fit with the current initial guess.  The
selected option in Figure~\ref{fig:AGAUS.init} is {\tt RE-GUESS} which
causes the task to change the plot to a spectrum of apparent optical
depth, such as that shown in \Hi{the figure at bottom}.  It will
then prompt you first to {\it ``Position cursor at center \&\ height
  of Gaussian component 1''}.  Move the cursor to the peak of
component 1 and press any TV button.  This selects the peak value and
center of component 1.  Then the task prompts you to {\it ``Position
  cursor at half-width of Gaussian component 1''}.  Move the cursor
horizontally to the approximate position of the half-power point of
component 1 and press any TV button.  The horizontal position of the
cursor then sets the initial guess of the full width of the component.
These prompts are then repeated for components two through {\tt
  NGAUSS}\@.  If you do not want to fit a particular component at
this position, move the cursor outside the rectangular border line
(\ie\ outside the data area of the plot) before pressing the TV
button for that component; it will be omitted.

\begin{figure}
\begin{center}
\resizebox{6.0in}{!}{\putfig{AGAUS.c}}
\centerline{\hphantom{MM}}
\resizebox{6.0in}{!}{\putfig{AGAUS.d}}
\caption{\Hi{Top: First spectrum to fit: better initial ``guess'' has
    been entered so {\tt DO FIT} should be selected.  Bottom: First
    spectrum to fit: good fit obtained so {\tt GOOD} or even {\tt TVOFF}
    should be selected.}}
\label{fig:AGAUS.good}
\label{fig:AGAUS.guessed}
\end{center}
\end{figure}

After the improved initial guess has been entered the plot is changed
to show the new guess, as illustrated in Figure~\ref{fig:AGAUS.guessed}.
This guess is good so the {\tt DO FIT} option is selected.  After TV
``buttons'' {\tt A}, {\tt B}, or {\tt C} are pressed the task attempts
the fit with the current initial guess.  Then the plot is changed with
the addition of the fit function in graphics plane 4 (usually cyan).
This is illustrated in Figure~\ref{fig:AGAUS.good}.  The individual
Gaussians are also plotted in a graphics plane \Hi{(7, usually a dirty
  yellow)} which is only visible where no other graphics plane has been
turned on.

A different menu appears at this point containing\\
\begin{center}
  \hicol
\begin{tabular}{|l|l|}\hline
   {\tt GOOD}     & Mark solution good and go on \\
   {\tt DO FIT}   & Attempt a new fit \\
   {\tt RE-GUESS} & Interactively enter a new initial guess \\
   {\tt TVOFF}    & Mark solution good and turn off interactivity \\
   {\tt HAND}     & Enter a solution from the terminal \\
   {\tt BAD}      & Mark pixel bad and go on \\
   {\tt 1}        & Interactively enter a 1-Gaussian initial guess \\
   {\tt 2}        & Interactively enter a 2-Gaussian initial guess \\
   {\tt 3}        & Interactively enter a 3-Gaussian initial guess \\
   {\tt ENTER NG} & Interactively enter a number of Gaussians and
                    an initial guess\\
   {\tt QUIT}     & Exit {\tt AGAUS} now \\ \hline
\end{tabular}
\end{center}
\hblack

The option to {\tt QUIT} causes the task to quit at this point.  You may
re-start later.  The option {\tt BAD} will mark this position as failed
and go on to the next position.   The option {\tt RE-GUESS} will loop
back to prompt you for a new guess.  This takes you back through the
steps shown in Figure~\ref{fig:AGAUS.guess} followed by that shown in
Figure~\ref{fig:AGAUS.guessed}.   Options {\tt 1}, {\tt 2}, \Hi{{\tt 3},
  {\tt 4}, {\tt ENTER NG} will loop back to plot an initial guess with
  the selected number of Gaussians.  The {\tt ENTER NG} option appears
  only when the current {\tt NGAUSS} is more than 4 and prompts you on
  the terminal to enter a number.}  ({\tt NGAUSS=3} in the
current example.)  Option {\tt HAND} will prompt you to enter using the
terminal the Gaussian parameters for each component.  Enter on one line
for each component, the peak value of the Gaussian (in optical depth),
the center (in pixels with respect to the reference pixel), and width
(in pixels).  Appropriate ranges of parameters in these units can be
seen from the display of the current fit values.  You may also enter
flags to cause one or more parameter values to be fixed should you
re-fit the current spectrum.  The flags are entered after the 3
parameter values, flags $\leq 0$ mean to hold the corresponding
parameter fixed and omitted flags are taken as 1.  {\tt AGAUS} will then
repeat the display in Figure~\ref{fig:AGAUS.good} to see if you made a
good guess.  Immediately after a {\tt HAND} operation only, the option
{\tt DO FIT} is offered to go back with the hand-entered values as the
initial guess for a new fit.

Option {\tt TVOFF} allows you to turn off interactivity, allowing the
task to run using its own initial guesses until it finds a completely
unreasonable solution or one with an rms greater than {\tt RMSLIMIT}\@.
When that happens, you are shown the offending fit parameters \Hi{and
the task resumes interactivity.  Frequently this will drop you
immediately into entering a new guess as in the bottom of
Figure~\ref{fig:AGAUS.guess} where the color change should make this
apparent.  Sometimes it simply shows something like the top of
Figure~\ref{fig:AGAUS.init} and you must select {\tt RE-GUESS} to try to
fix things.}  Option {\tt GOOD} tells the task that you are (reasonably)
happy and that it should go on to the next position.

When fitting only a single Gaussian, {\tt AGAUS} makes an initial
guess based mostly on finding a real peak in the spectrum.  This is
quite reliable, so turning off the TV interaction may save a great
deal of effort, although there will possibly be bad positions to be
fixed up in the next stage of this task.

\subsection{Editing and output}

\begin{figure}
\begin{center}
\resizebox{5.8in}{!}{\putfig{AGAUS.e}}
\caption{\Hi{Model source residual rms image.  The bright ``rims''
    suggest that a lower {\tt FLUX} cutoff would be useful.}}
\label{fig:AGAUS.edit}
\end{center}
\end{figure}

Eventually all positions selected by {\tt FLUX} and {\tt BLC} and {\tt
  TRC} will have been fit.  At this point, the task computes images of
the fit parameters plus the ``flux'' (area under the Gaussian) and
their uncertainties.  \Hi{An image of the rms over the first axis (after
  any fit components are subtracted) is also computed in the September
  {\tt 31DEC25} version (see Figure~\ref{fig:AGAUS.edit}).  This
  ``edit'' stage is omitted if the input image is one dimensional, but,
  in that case, channel flagging is available in the initial fitting of
  the spectrum.}  {\tt AGAUS} then offers a lengthy menu of options
which will allow you to view these images and revisit positions that
seem to have produced incorrect fits.  If {\tt NGAUSS} $> 1$, options to
swap portions of image $n$ with corresponding portions of image $m$ are
also offered.  This ``edit'' menu is illustrated in
Figure~\ref{fig:AGAUS.edit}.  \Hi{For small images,}  {\tt AGAUS}
replicates pixels in both directions to make the image large enough to
see.

There are three kinds of editing implemented here.  In the first, the
user establishes the parameter extrema which should be viewed as
acceptable.  The extrema currently set are shown in the title lines.
\Hi{The {\tt SET} options let you set the maximum residual and, for each
Gaussian, the minimum signal-to-noise ratio, the minimum and maximum of
the peak optical depth, the minimum and maximum of the center pixel,
the minimum and maximum of the width, and the maximum error in the
width.}  Then, {\tt AGAUS} may be told to flag all solutions not meeting
these criteria, or, more profitably perhaps, to revisit those positions
to see if a better fit can be obtained.  The other editing methods are
similar, but act on a list of pixel positions.  These may be entered
by typing in values or by clicking on suspect pixel positions in the
{\tt CURVALUE} function described below \Hi{or by selecting the
{\tt BLOTCH LIST} function also described below}.  The contents of the
list may be viewed, the solutions at the positions may be flagged, or
they may be revisited to attempt for a better solution, or the solutions
at the listed positions may be swapped between components $n$ and $m$.
The menu will offer only appropriate swaps between components, thus 1,
2, and 3 in our {\tt NGAUSS=3} example.  Swapping may be required if
{\tt AGAUS} gets confused as to which component you want to call number
1 and which number 2.  After the flagging, revisiting, or swapping, the
list is cleared.    The first column of the menu shows the following:\\
\vfill\eject


\begin{figure}
\begin{center}
\resizebox{6.0in}{!}{\putfig{AGAUS.rc}}
\caption{\Hi{Spectrum to be re-done after doing a {\tt RE-GUESS}.
    {\tt FLAG+FIT} selected for illustrative purposes.}}
\label{fig:AGAUS.redo}
\end{center}
\end{figure}

\begin{figure}
\begin{center}
\resizebox{5.0in}{!}{\putfig{AGAUS.rc2}}
\centerline{\hphantom{MM}}
\resizebox{5.0in}{!}{\putfig{AGAUS.rd}}
\caption{\Hi{Top:Spectrum to be re-done in flag menu.  Some channels on
    the right hand side are flagged and the pink lines show another
    range of channels which could be flagged.  Bottom: Acceptance menu
    after {\tt FLAG+FIT}.}}
\label{fig:AGAUS.flag}
\end{center}
\end{figure}

\begin{center}
\begin{tabular}{|l|l|}\hline
 {\tt EXIT           } & Exit {\tt AGAUS}, writing output images if
                         {\tt DOOUTPUT} is now $> 0.$\\
 {\tt SET MIN S/N    } & Set minimum amplitude S/N(s) for okay
                         solutions\\
 {\tt SET MAX RES    } & Set maximum residual for okay solutions\\
 {\tt SET PEAK RANGE } & Set peak value range(s) for okay solutions\\
 {\tt SET \Me{CENTER} RANGE } & Set \Me{X center} range(s) for okay solutions\\
 {\tt SET WIDTH RANGE} & Set width range(s) for okay solutions\\
 {\tt SET MAX ERR WID} & Set maximum error(s) in width for okay
                         solutions\\
 {\tt REDO ALL       } & Re-do all solutions which are not okay
                         following the above criteria\\
 {\tt FLAG ALL       } & Mark bad all solutions which are not okay\\
 {\tt OFF ZOOM       } & Turn of TV zoom\\
 {\tt OFF TRANSFER   } & Turn off black \&\ white and color TV
                         enhancements\\
 {\tt \Me{RESET WINDOW}} & \Me{Display full view of current image} \\
 {\tt \Me{LABEL WEDGE?}} & \Me{Turn on/off labeling of step wedge} \\
 {\tt SET DOOUTPUT   } & Increment {\tt DOOUTPUT} in loop 0-3 --- with
                         1 and 3 causing residual\\
                       & images and 2 and 3 causing parameter images
                         to be written on {\tt EXIT}\\
 {\tt ADD TO LIST    } & Type in output pixel coordinates to add to
                         list\\
 {\tt SHOW LIST      } & Display coordinates in list\\
 {\tt REDO LIST      } & Re-do solutions for all pixels in list\\
 {\tt FLAG LIST      } & Flag solutions for all pixels in list\\
 {\tt SWAP LIST 1-2  } & Swap solutions for components 1 and 2 for all
                         pixels in list\\
 {\tt SWAP LIST 1-3  } & Swap solutions for components 1 and 3 for all
                         pixels in list\\
 {\tt SWAP LIST 2-3  } & Swap solutions for components 2 and 3 for all
                         pixels in list\\ \hline
\end{tabular}
\end{center}

\hicol
In {\tt 31DEC25}, {\tt AGAUS} offers an additional capability in the
edit stage.\footnote{\Hi{This option is available at the beginning when
    the input image is one-dimensional.}}  When doing {\tt REDO ALL} and
{\tt REDO LIST}, the menu shown in Figure~\ref{fig:AGAUS.init} and
Figure~\ref{fig:AGAUS.guessed} has an additional option {\tt FLAG+FIT}
as shown in Figure~\ref{fig:AGAUS.redo}.  When this option is selected a
new menu is shown as in Figure~\ref{fig:AGAUS.flag}:
\begin{center}
\begin{tabular}{|l|l|}\hline
  {\tt UNDO ALL}   & Undo all channel flagging \\
  {\tt FLAG CHANS} & Interactively flag a range of channels \\
  {\tt UNDO CHANS} & Interactively undo flags in a range of channels \\
  {\tt RE-GUESS}   & Interactively enter a new guess for the
                     Gaussians \\
  {\tt DO THE FIT} & Leave the flag routine and do the fit \\ \hline
\end{tabular}
\end{center}

Flagged channels are plotted in a different color (usually reddish)
than unflagged channels (usually yellow).  {\tt UNDO ALL} simply removes
all flags in the current spectrum.  {\tt FLAG CHANS} and {\tt UNDO
  CHANS} bring up two vertical lines (usually pink in color).  The
cursor position controls the position of the lines, button A switches
between the two, button B sets a channel range and continues, button C
sets a range and exits, and button D exits without setting a new range.
{\tt RE-GUESS} takes you to the screen to set a new guess
(Figure~\ref{fig:AGAUS.guess}) and then returns to this flag menu.
Finally {\tt DO THE FIT} attempts the Gaussian fit and returns to the
menu to accept the result.  That screen is illustrated in the bottom of
Figure~\ref{fig:AGAUS.flag}.  Note the {\tt FLAG+REDO} option added to
this menu in the edit phase.  That option takes you back through the
sequence just illustrated.
\hblack

\Hi {When the {\tt XG} table is created with fewer than six Gaussians,
  the second column of the main edit menu contains the rms image plus}
{\tt NGAUSS} sets of functions
\begin{center}
\begin{tabular}{|l|l|}\hline
 \Hi{\tt {SHOW IMAGE RMS}} & \Hi{Enter image interaction with the
                     residual rms image}\\
 {\tt SHOW IMAGE A1 } & Enter image interaction with peak value of
                     component 1\\
 {\tt SHOW IMAGE C1 } & Enter image interaction with center pixel of
                     component 1\\
 {\tt SHOW IMAGE W1 } & Enter image interaction with width of
                     component 1\\
 {\tt SHOW IMAGE F1 } & Enter image interaction with "flux" of
                     component 1\\
 {\tt SHOW IMAGE EA1} & Enter image interaction with uncertainty in
                     peak value of component 1\\
 {\tt SHOW IMAGE EC1} & Enter image interaction with uncertainty in
                     center pixel of component 1\\
 {\tt SHOW IMAGE EW1} & Enter image interaction with uncertainty in
                     width of component 1\\
 {\tt SHOW IMAGE EF1} & Enter image interaction with uncertainty in
                     "flux" of component 1\\ \hline
\end{tabular}
\end{center}

\hicol
\begin{figure}
\begin{center}
\resizebox{6.0in}{!}{\putfig{AGAUS.6comp}}
\caption{Edit menu when more than 5 components.  The rms image is shown
  with component 4 selected.}
\label{fig:AGAUS.6comp}
\end{center}
\end{figure}

When the {\tt XG} table is created with more than 5 components, these
menus change as illustrated in Figure~\ref{fig:AGAUS.6comp}.  The
{\tt SWAP LIST} option lists all possible swaps for the first 5
Gaussians.  The added option {\tt SWAP LIST M - N} prompts the user on
the terminal for the two components to be switched using the pixel list.
The right-hand column changes significantly.  Only one component can be
viewed at any one time, with the {\tt CHOOSE COMP $nn$} option to select
the desired component.  For this figure, the user has looked at the rms
image and then selected Gaussian component 4 to be examined.  The
right-hand menu becomes
\begin{center}
  \begin{tabular}{|l|l|}\hline
 {\tt SHOW IMAGE RMS} & Enter image interaction with the
                     residual rms image\\
 {\tt SHOW IMAGE A4 } & Enter image interaction with peak value of
                     component 4\\
 {\tt SHOW IMAGE C4 } & Enter image interaction with center pixel of
                     component 4\\
 {\tt SHOW IMAGE W4 } & Enter image interaction with width of
                     component 4\\
 {\tt SHOW IMAGE F4 } & Enter image interaction with "flux" of
                     component 4\\
 {\tt SHOW IMAGE EA4} & Enter image interaction with uncertainty in
                     peak value of component 4\\
 {\tt SHOW IMAGE EC4} & Enter image interaction with uncertainty in
                     center pixel of component 4\\
 {\tt SHOW IMAGE EW4} & Enter image interaction with uncertainty in
                     width of component 4\\
 {\tt SHOW IMAGE EF4} & Enter image interaction with uncertainty in
                       "flux" of component 4\\
 {\tt CHOOSE COMP  1} & Change attention to Gaussian component 1.\\
 {\tt CHOOSE COMP  2} & Change attention to Gaussian component 2.\\
 {\tt CHOOSE COMP  3} & Change attention to Gaussian component 3.\\
 {\tt CHOOSE COMP  4} & Change attention to Gaussian component 4.\\
 {\tt CHOOSE COMP  5} & Change attention to Gaussian component 5.\\
 {\tt CHOOSE COMP  6} & Change attention to Gaussian component
                        6.\\ \hline
\end{tabular}
\end{center}

When you select one of the {\tt SHOW IMAGE} \hblack functions most of
the following operations will appear in yet another menu.  This image
interaction menu is illustrated in Figure~\ref{fig:AGAUS.image}.  Only
one of the {\tt LOAD AS} options will appear, with the next one in the
sequence offered when the current one has been invoked.  The {\tt SET
  WINDOW} option allows you to select a sub-image to view in greater
detail, while {\tt RESET WINDOW} returns to viewing the full image.
\Hi{The {\tt BLOTCH LIST} option allows you to set an area of the image
  to be added to the list of pixels to be addressed later with {\tt REDO
    LIST}, {\tt FLAG LIST}, or {SWAP LIST.}\@.}  The {\tt SWAP $n$-$m$}
options will appear as needed when {\tt NGAUSS} $ > 1$ and are used to
reverse your selection of component number $n$ and component $m$ in case
{\tt AGAUS} got confused.  The {\tt NEXT WINDOW} option appears when
needed to display an image too large to fit on the display screen.
These options mostly invoke familiar functions from \AIPS\ to control
the {\tt FUNCTYPE} used in loading the image to the display, to enhance
the image intensities, to color the enhanced image intensities, and to
zoom the display.
\vfill\eject

\begin{center}
\begin{tabular}{|l|l|}\hline
 {\tt RETURN     } & Return to the above menus, image stays displayed\\
 {\tt LOAD AS SQ } & Re-load image with square root transfer function\\
 {\tt LOAD AS LG } & Re-load image with log transfer function\\
 {\tt LOAD AS L2 } & Re-load image with extreme log transfer function\\
 {\tt LOAD AS LN } & Re-load image with linear transfer function\\
 {\tt SET WINDOW } & Set a sub-image to view\\
 {\tt RESET WINDOW} & Return too viewing the full image\\
 {\tt OFF TRANSF } & Turn off enhancement done with {\tt TVTRANSF}\\
 {\tt OFF COLOR  } & Turn off color enhancements\\
 {\tt TVTRANSF   } & Black \&\ white image enhancement\\
 {\tt TVPSEUDO   } & Color enhancement of numerous sorts\\
 {\tt TVPHLAME   } & Color enhancement of flame type, multiple colors\\
 \Hi{{\tt OFMCOLOR }} & \Hi{Many standard color tables (OFMs)
                     available} \\
 {\tt TVZOOM     } & Interactive zooming and centering of image\\
 {\tt CURVALUE   } & Display value under cursor, mark pixels for list\\
\Hi{\tt BLOTCH LIST} & \Hi{Interactively add a blotch area to the pixel
                     list} \\
 {\tt SWAP 1-2   } & Swap solutions for components 1 and 2
                     interactively\\
 {\tt SWAP 1-3   } & Swap solutions for components 1 and 3
                     interactively\\
 {\tt NEXT WINDOW} & Move to next window in large images\\ \hline
\end{tabular}
\end{center}

\hicol
\begin{figure}
\begin{center}
\resizebox{5.25in}{!}{\putfig{AGAUS.f}}
\caption{Image of model Gaussian component 4 when {\tt NGAUSS} = 6.}
\label{fig:AGAUS.image}
\end{center}
\end{figure}
\hblack

Two operations in this menu are different from the usual.  {\tt
  CURVALUE} provides the capability of selecting positions for the
edit ``list.''  During the {\tt CURVALUE} operation position the
cursor over the desired pixel and press buttons {\tt A}, {\tt B}, or
{\tt C} to add that pixel to the list.  The \Hi{{\tt BLOTCH LIST} and}
{\tt SWAP $n$-$m$} operations use a TV blotch operation like that in the
\AIPS\ verb {\tt TVSTAT} and task {\tt BLSUM}\@.  You are to mark with a
``blotch'' region those pixels in the present image which \Hi{are to be
  added to the list} or are to have their solutions swapped with those
of the selected component.  Instructions will appear in the message
window as you proceed.  Begin by positioning the cursor at a pixel to be
the first vertex of a connected sequence of vertices and press TV button
{\tt A}\@.  Move to the next vertex and press button {\tt A} again and
repeat until you have marked all vertices for this region.  Then press
button {\tt D} if you are done with this region or button {\tt C} if you
need to re-position one of the vertices.  In this case, move the cursor
to the vertex to be re-positioned, press button {\tt A} and drag the
vertex to the corrected position.  Press button {\tt A} or {\tt B} to
fix that vertex and go on to reset another vertex or {\tt D} to end this
region.  You may do this as many times as needed.

When you have finished getting the images just the way you want them,
you may write them out as \AIPS\ image files.  Select the {\tt SET
  DOOUTPUT} option until its value, shown at the top of the screen, is
what you want.  In {\tt AGAUS}, values \Hi{1, 3, 5, and 7 cause a
residual image cube to be written, values 2, 3, 6 and 7 cause images of
the parameter values and their uncertainties to be written, and values 4,
5, 6, and 7 cause the image of the residual rms to be written.}  The
baseline and slope images and their uncertainties are given class {\tt
  CONST}, {\tt SLOPE}, {\tt DCONST}, and {\tt DSLOPE}, while the
parameter images and their uncertainties get class \Hi{{\tt AMPL$nn$},
  {\tt CENT$nn$}, {\tt WIDT$nn$}, {\tt DAMP$nn$}, {\tt DCEN$nn$}, and
  {\tt DWID$nn$}, and the flux and its uncertainty get class {\tt
    FLUX$nn$}, and {\tt DFLX$nn$}, where $nn$} is the component number.
\Hi{The residual rms image gets class {\tt RESRMS}\@.}

%\vfill\eject
\section{Zeeman splitting: {\tt ZAMAN}}

When an intrinsically unpolarized spectral line is emitted in the
presence of a magnetic field, the right and left circular
polarizations have their frequencies shifted in opposite directions by
an amount proportional to the magnetic field (at least for modest
magnetic fields).  The traditional analysis of data to measure this
splitting works only for those cases in which the separation of
polarizations is a small fraction of the line width.  In that case,
the function that has been traditional is
\begin{equation}
     V(x,y,z) = A(y,z) I(x,y,z) + 0.5 B(y,z)\,\, \frac{dI(x,y,z)}{dx}
\label{eqn:Zeman}
\end{equation}
where $V(x,y,z)$ is the V Stokes polarization component. $I(x,y,z)$ is
the unpolarized I Stokes component, $x$ is the spectral axis value,
$(y,z)$ is the celestial coordinate value, and $A(y,z)$ and $B(y,z)$
are the parameters to be found by a linear least-squares method.
\footnote{Sault, R.J., Killeen, N. E. B.., Zmuidzinas, J., Loushin, R.
  1990, {\it Ap.~J.}, {\bf 74}, 437-461.}  The \AIPS\ task {\tt ZAMAN}
offers this model, with two choices for the method by which the
derivative of $I$ with $x$ is computed.

If the total intensity spectrum has had {\tt AGAUS} applied, another
function may be used instead.  I present below a derivation of the
formula for absorption, neglecting the leakage term until the end.
Let us assume that the optical depth is due to a sum of Gaussians each
having its own depth, center channel, and width.  Thus
\begin{eqnarray}
   I(x,y,z) & = & C(y,z) exp (-\sum_1^{\tt NGAUSS} \tau_i(x,y,z) ) \\
            & = & C(y,z) \prod_1^{\tt NGAUSS} exp (-\tau_i(x,y,z))
\end{eqnarray}
When shifted by magnetic fields, assumed different for each Gaussian,
the formula for the V Stokes becomes
\begin{eqnarray}
  V(x,y,z) & \equiv & C(y,z) \left( \prod_1^{\tt NGAUSS} exp
            (-\tau_{iR}(x,y,z)) - \prod_1^{\tt NGAUSS} exp
            (-\tau_{iL}(x,y,z)) \right) \\
           & = & C(y,z) \prod_1^{\tt NGAUSS} exp (-\tau_{iA})
            exp (-(\tau_{iR}-\tau_{iA})) - \prod_1^{\tt NGAUSS}
             exp (-\tau_{iA}) exp (-(\tau_{iL}-\tau_{iA}))
             \label{eqn:ZGdiff}
\end{eqnarray}
where we assume that the difference between $\tau_{iL}$ and
$\tau_{iA}$ is small.  Then
\begin{eqnarray}
exp (-(\tau_{iL}-\tau_{iA})) & \approx & 1 + \tau_{iA} - \tau_{iL} \\
  & = & 1 + \tau_{i0} \left( \exp(-\alpha (x-x_i)^2/\sigma_i^2) -
        \exp (-\alpha (x - (x_i + \delta_i/2))^2 / \sigma_i^2)
        \right) \\
  & \approx & 1 + \tau_{i0} \exp (-\alpha (x - x_i)^2/\sigma_i^2)
             \left[ 1 - exp (\alpha (x-x_i)\delta_i/\sigma_i^2 -
               \alpha\delta_i^2/(4\sigma_i^2)) \right] \\
  & \approx & 1 + \tau_{i0} \exp(-\alpha (x - x_i)^2/\sigma_i^2)
                \left[ -\alpha (x-x_i)\delta_i/\sigma_i^2 \right] \\
exp (-(\tau_{iR}-\tau_{iA})) & \approx & 1 + \tau_{i0}
          \exp(-\alpha (x - x_i)^2/\sigma_i^2)
          \left[ \alpha (x-x_i)\delta_i/\sigma_i^2 \right]
\end{eqnarray}
Thus each of the terms in Equation~\ref{eqn:ZGdiff} is of the form
\begin{eqnarray}
  & = & C(y,z) \prod_1^{\tt NGAUSS} exp (-\tau_{iA}) (1 \pm a_i) \\
  & = & C(y,z) exp (-\sum\tau_i) \prod_1^{\tt NGAUSS} (1 \pm a_i) \\
  & \approx & C(y,z) exp (-\tau) \left( 1 \pm \sum a_i \right)
\end{eqnarray}
We note that the product of the $\exp (-\tau_{iA})$ is just the total
absorption factor $\exp (-\tau)$ and the product of a number of
$(1 \pm a_i)$, where $a_i$ is small, is approximately $1 \pm \sum
a_i$.  We end up with
\begin{eqnarray}
  \tau(x,y,z) & = & \sum_1^{\tt NGAUSS} \tau_{i0} \exp (-\alpha
              (x-x_i)^2 / \sigma_1^2) \\
  V(x,y,z) & \approx & C(y,z) exp (-\tau(x,y,z)) \sum_1^{\tt NGAUSS}
              (2 \tau_i \alpha (x - x_i) \delta_i / \sigma_i^2)
              exp (-\tau_i(x,y,z)) \label{eqn:ZemanGaus}\\
  V(x,y,z) & = & A(y,z) I(x,y,z) + 0.5 \sum_1^{\tt NGAUSS} B_i(y,z)\,
        \,\frac{-d\tau_i(x,y,z)}{dx}
\end{eqnarray}
where $\tau_i(x,y,z)$ is the spectrum of the $i$'th Gaussian component
in the absorption and one solves for the I polarization leakage
$A(y,z)$ and {\tt NGAUSS} component frequency separations $B_i(y,z)$.
Any association of $B_i(y,z)$ with magnetic field values is left to
the user.

\subsection{Inputs}

The inputs for {\tt ZAMAN} are very similar to those for {\tt AGAUS}\@.
{\tt INNAME} {\it et al.}~specify the V polarization cube which must be
in transposed form with frequency/velocity as the first axis.  {\tt
  IN2NAME} {\it et al.}~specify the corresponding I polarization cube,
similarly transposed.  The axes of the two images must match.  {\tt BLC}
and {\tt TRC} define the spectral and celestial coordinate regions of
interest for the fit and {\tt FLUX} gives the lower limit in the I image
for the average of three consecutive channels for the spectra to be fit.
{\tt INVERS} specifies the input version of the {\tt ZE} table in which
the results are stored.  Zero means to make a new one, other values mean
to re-visit an existing solution.  Adverb {\tt OPTYPE} specifies which
of the above formul\ae\ are solved.  {\tt OPTYPE = 'GAUS'} says to use
the {\tt XG} file {\tt IN2VERS} attached to the input I polarization
cube to solve using Equation~\ref{eqn:ZemanGaus}.  {\tt OPTYPE = '2SID'}
says to solve Equation~\ref{eqn:Zeman}, evaluating the derivative by
$$
\frac{dI(x,y,z)}{dx} = 0.5 \left[\, I(x+1,y,z) - I(x-1,y,z) \,\right]
$$
while any other {\tt OPTYPE} value says to evaluate the derivative
with
$$
\frac{dI(x,y,z)}{dx} = I(x,y,z) - I(x-1,y,z)
$$
while solving Equation~\ref{eqn:Zeman}.  {\tt DOOUTPUT} controls what
files are written --- this may be changed interactively \Hi{(except for
one-dimensional images)} so leave it zero at this point.  Set
\Hi{{\tt DOTV = 1}} to use TV menus to prompt you.  Even though the
fitting operation is linear and so needs little or no guidance, it is
best to watch what is happening so you should never set this adverb
false.  If all seems well, you can turn off the TV after watching a few
of the solutions.  $A(y,z)$ is always fit, but should be vanishingly
small if {\tt ZAMAN} is applied to a cube written by {\tt ZAMAN} with
the leakage removed.  {\tt RMSLIMIT} is an upper limit for the rms of a
fit before the fit is viewed as ``failed'' which causes the TV and
interaction to be turned back on after you have turned it off.  You
should get a good idea of an appropriate value from your initial uses of
{\tt ZAMAN} or from your knowledge of the noise in your data cube.

\begin{figure}
\begin{center}
\resizebox{6.0in}{!}{\putfig{ZAMAN.a}}
\caption{\Hi{First model spectrum to fit, initial ``guess'' has Gaussians
  but the two $B_i(y,z)$ are zero.}}
\label{fig:ZAMAN.init}
\end{center}
\end{figure}

{\tt ZAMAN} has one additional adverb, {\tt DOCONT}, for which the
special value $-2$ causes changed behavior in the fitting.  (A special
value was chosen to avoid accidental use of this option since {\tt
  DOCONT} is used by a number of other tasks.)  If the Vpol image cube
was produced from continuum-subtracted visibilities (\ie\ the output
of {\tt UVLSF} or {\tt UVLIN}), then the actual Ipol leakage will be
proportional to the continuum subtracted Ipol, $I(x,y,z) - C(y,z)$
rather than $I(x,y,z)$\@.  {\tt ZAMAN} does the fitting differently
when this option is selected and records the fact in the {\tt ZE}
table by setting the keyword {\tt ABSORPTN} to 2, rather than the
usual 1 for normal absorption modeling.  The post-fitting plot task
{\tt XG2PL} uses this keyword value to honor the changed meaning of
the leakage gain.
\vfill\eject

\subsection{Fitting}

\begin{figure}
\begin{center}
\resizebox{5.2in}{!}{\putfig{ZAMAN.b}}
\centerline{\hphantom{MM}}
\resizebox{5.2in}{!}{\putfig{ZAMAN.c}}
\caption{\Hi{Top: First model spectrum to fit plotted after fitting.
  Bottom: Next model spectrum, initial ``guess'' in green has Gaussians
  and values for $B_i(y,z)$, fit is in cyan.}}
\label{fig:ZAMAN.init2}
\end{center}
\end{figure}

The fitting process starts with a plot of the I polarization spectrum
across the top and the V polarization across the bottom.  The data
and axis labels are plotted in graphics channel one (usually yellow)
and the initial guess as lines in graphics channel two (usually
green).  The Gaussians, when {\tt OPTYPE='GAUS'}, are shown as a
smooth line on the I polarization plot, while the initial guess,
plotted in the V polarization, is plotted at the locations of the data
samples.  Then you are offered a menu of options, as shown in the
present figures, on the TV (\Hi{{\tt DOTV}$> 0$}).  The first spectrum
to be fit (from the model of the absorption shown for {\tt AGAUS}) is
illustrated in Figure~\ref{fig:ZAMAN.init} showing that the first guess
has zero for the three $B_i(y,z)$ \Hi{and also, in this case, $A(y,z)$.
With a good guess for the gain, the green line can mimic} the shape of
the I spectrum, not the V spectrum.  The menu that appears at this point
is\\
\begin{center}
  \hicol
\begin{tabular}{|l|l|}\hline
   {\tt DO FIT}   & To do the fitting \\
   {\tt BAD}      & To mark this voxel bad and go on to the next \\
   {\tt QUIT}     & To exit {\tt ZAMAN} now \\ \hline
\end{tabular}
\end{center}
\hblack

Note that there is no {\tt RE-GUESS} since there is no need to enter
them with linear least squares.  You select menu options in the same
way as {\tt AGAUS}, with ``button'' {\tt D} giving appropriate
real-time help information and buttons {\tt A}, {\tt B}, and {\tt C}
selecting the highlighted option.  The option to {\tt QUIT} causes the
task to quit at this point.  You may re-start later.  The option {\tt
  BAD} will mark this position as failed and go on to the next position.
The option {\tt DO FIT}, currently highlighted, will cause the task to
attempt the linear fit with the current initial guess.  The result of
that fit is shown in the top Figure~\ref{fig:ZAMAN.init2}.
\hicol The menu at this point contains\\
\begin{center}
\begin{tabular}{|l|l|}\hline
   {\tt GOOD}   & To accept the solution and go on \\
   {\tt TVOFF}  & To accept the solution and go on with no interaction \\
   {\tt HAND}   & To enter a new solution from the terminal \\
   {\tt BAD}    & To mark this solution as bad and go on  \\
   {\tt QUIT}   & To exit {\tt ZAMAN} now \\ \hline
\end{tabular}
\end{center}
What most of these do is obvious.  {\tt HAND} prompts you to enter the
Gain value and then either {\it Enter avg Field in channels} or {\it
  Enter Gaussian xx Field in channels} for {\it xx} $= 1$ to {\tt
  NGAUSS} depending on the {\tt OPTYPE} selected.  When you have entered
all values, {\tt ZAMAN} repeats the plot at the top of
Figure~\ref{fig:ZAMAN.init2} with the new values.  When the task goes on
to the next voxel it starts with the $B_i(y,z)$ of the last fit (bottom
of Figure~\ref{fig:ZAMAN.init2}) and so has a much better initial guess.
\hblack

\subsection{Editing and output}

Eventually all positions selected by {\tt FLUX} and {\tt BLC} and {\tt
  TRC} will have been fit.  At this point, the task computes images of
\Hi{residual spectral rms} and the fit parameters $A(y,z)$ and $B_i(y,z)$
and their uncertainties.  \Hi{This ``edit'' stage is omitted if the
  input image is one dimensional, but, in that case, channel flagging is
  available in the initial fitting of the spectrum.}  {\tt ZAMAN} then
offers a menu of options which will allow you to view these images and
revisit positions that seem to have produced incorrect fits.  This
``edit'' menu is illustrated in Figure~\ref{fig:ZAMAN.edit}.  If {\tt
  SET WINDOW} is used to select a small sub-image, then {\tt ZAMAN} will
blow it up by pixel replication to a reasonable size as in the
figure. The first column of the menu includes:\\
\vfill\eject

\begin{figure}
\begin{center}
\resizebox{5.5in}{!}{\putfig{ZAMAN.d}}
\caption{\Hi{{\tt ZAMAN} fit and image editing screen; image shown is the
  uncertainty in the field of component 1.  Coloring from {\tt OFMCOLOR}
  of button C.}}+
\label{fig:ZAMAN.edit}
\end{center}
\end{figure}

\begin{center}
\begin{tabular}{|l|l|}\hline
 {\tt EXIT           } & Exit {\tt AGAUS}, writing output images if
                         {\tt DOOUTPUT} is now $> 0.$\\
 {\tt SET MAX RES    } & Set maximum residual for okay solutions\\
 {\tt SET GAIN RANGE } & Set gain value range(s) for okay solutions\\
 {\tt SET FIELD RANGE } & Set field range(s) for okay solutions\\
 {\tt SET MAX ERR FLD} & Set maximum error(s) in field for okay
                         solutions\\
 {\tt REDO ALL       } & Re-do all solutions which are not okay\\
 {\tt FLAG ALL       } & Mark bad all solutions which are not okay\\
 {\tt OFF ZOOM       } & Turn of TV zoom\\
 {\tt OFF TRANSFER   } & Turn off black \&\ white and color TV
                         enhancements\\
 {\tt RESET WINDOW}    & Display full view of current image \\
 {\tt LABEL WEDGE?}    & Turn on/off labeling of step wedge \\
 {\tt SET DOOUTPUT   } & Increment {\tt DOOUTPUT} in loop 0-3 --- with
                         1 and 3 causing residual\\
                       & images and 2 and 3 causing parameter images
                         to be written on {\tt EXIT}\\
 {\tt ADD TO LIST    } & Type in output pixel coordinates to add to
                         list\\
 {\tt SHOW LIST      } & Display coordinates in list\\
 {\tt REDO LIST      } & Re-do solutions for all pixels in list\\
 {\tt FLAG LIST      } & Flag solutions for all pixels in list\\ \hline
\end{tabular}
\end{center}

There are two kinds of editing implemented here.  In the first, the
user establishes the parameter extrema which should be viewed as
acceptable.  The extrema currently set are shown in the title lines
and include the maximum rms, the range of allowed values for ``gain''
($A(y,z)$), the range of allowed values for ``field'' ($B(y,z)$ in
pixels), and the maximum uncertainty in the field.  Then, {\tt ZAMAN}
may be told to flag all solutions not meeting these criteria, or, more
profitably perhaps, to revisit those positions to see why a poor fit
was obtained.  Note that, unlike {\tt AGAUS}, the linear nature of the
fit in {\tt ZAMAN} means that only one solution is possible at each
celestial coordinate \Hi{without a change to the Gaussian model or to
  the data of the spectrum}.  The other editing method is similar, but
acts on a list of pixel positions.  These may be entered by typing in
values, by clicking on suspect pixel positions in the {\tt CURVALUE}
function described below, \Hi{or by the {\tt BLOTCH LIST} function also
  described below}.  The contents of the list may be viewed, the
solutions at the positions may be flagged, and they may be revisited to
see why they are suspect.  Note that there are no swapping of solutions
in this task; {\tt AGAUS} establishes which component is which.  After
the flagging or revisiting, the list is cleared.

\begin{figure}
\begin{center}
\resizebox{5.5in}{!}{\putfig{ZAMAN.f}}
\caption{\Hi{{\tt ZAMAN} initial display to re-do a fit.}}
\label{fig:ZAMAN.redo1}
\end{center}
\end{figure}

\hicol
In {\tt 31DEC25} the operations of {\tt REDO ALL} and {\tt REDO LIST}
offer an additional menu option.\footnote{\Hi{This option is available
at the beginning when the input image is one-dimensional.}}  When a
spectrum to be re-done is first displayed it is called {\tt FLAG
  \&\ FIT} as illustrated in Figure~\ref{fig:ZAMAN.redo1}.  If this
option is selected the screen shown in the upper portion of
Figure~\ref{fig:ZAMAN.redo2} appears.  The menu contains\\
\begin{center}
\begin{tabular}{|l|l|}\hline
  {\tt UNDO ALL}   & Undo all channel flagging \\
  {\tt FLAG CHANS} & Interactively flag a range of channels \\
  {\tt UNDO CHANS} & Interactively undo flags in a range of channels \\
  {\tt DO THE FIT} & Leave the flag routine and do the fit \\ \hline
\end{tabular}
\end{center}

\begin{figure}
\begin{center}
\resizebox{5.2in}{!}{\putfig{ZAMAN.g}}
\centerline{\hphantom{MM}}
\resizebox{5.2in}{!}{\putfig{ZAMAN.h}}
\caption{\Hi{Top: Spectrum to be re-done in flag menu.  Some channels on
    the right hand side are flagged and the pink lines show another
    range of channels which could be flagged.  Bottom: Acceptance menu
    after {\tt FLAG \&\ FIT}.}}
\label{fig:ZAMAN.redo2}
\end{center}
\end{figure}

Flagged channels are plotted in a different color than unflagged
channels (usually reddish and yellow, respectively).  {\tt UNDO ALL}
simply removes all flags on the current spectrum.  {\tt FLAG CHANS} and
{\tt UNDO CHANS} bring up two vertical lines (usually pink in color).
The cursor position controls the position of the lines, button A
switches between the two, button B sets a channel range and continues,
button C sets a range and exits, and button D exits without setting a
new range.  Finally {\tt DO THE FIT} attempts the Zeeman fit and returns
to the menu to accept the result.  That screen is illustrated in the
bottom of Figure~\ref{fig:ZAMAN.redo2}.  Note the {\tt FLAG+REDO} option
added to this menu in the edit phase.  That option takes you back
through the sequence just illustrated.
\hblack
%\vfill\eject

The second column of the main edit menu contains
\begin{center}
\begin{tabular}{|l|l|}\hline
 {\tt SHOW IMAGE G } & Enter image interaction with gain\\
 {\tt SHOW IMAGE EG } & Enter image interaction with uncertainty in
                     the gain\\
 {\tt SHOW IMAGE F1 } & Enter image interaction with field of
                     component 1\\
 {\tt SHOW IMAGE EF1} & Enter image interaction with uncertainty in
                     field of component 1\\
 {\tt SHOW IMAGE F2 } & Enter image interaction with field of
                     component 2\\
 {\tt SHOW IMAGE EF2} & Enter image interaction with uncertainty in
                     field of component 2\\
 {\tt SHOW IMAGE F3} & Enter image interaction with field of component
                     3\\
 {\tt SHOW IMAGE EF3} & Enter image interaction with uncertainty in
                     field of component 3\\ \hline
\end{tabular}
\end{center}
There is 1 or, if {\tt OPTYPE='GAUS'} as in the illustrated cases,
the maximum of {\tt NGAUSS} of the {\tt F}$n$ and {\tt EF}$n$ options.
When you select one of the {\tt SHOW} options, the options in yet
another menu appear along with a display of the selected image.  As
illustrated in Figure~\ref{fig:ZAMAN.field1}, these options are
%\vfill\eject
\begin{center}
\begin{tabular}{|l|l|}\hline
 {\tt RETURN     } & Return to the above menus, image stays displayed\\
 {\tt LOAD AS SQ } & Re-load image with square root transfer function\\
 {\tt LOAD AS LG } & Re-load image with log transfer function\\
 {\tt LOAD AS L2 } & Re-load image with extreme log transfer function\\
 {\tt LOAD AS LN } & Re-load image with linear transfer function\\
 {\tt SET WINDOW } & Set a sub-image to view\\
 {\tt RESET WINDOW} & Return too viewing the full image\\
 {\tt OFF TRANSF } & Turn off enhancement done with {\tt TVTRANSF}\\
 {\tt OFF COLOR  } & Turn off color enhancements\\
 {\tt TVTRANSF   } & Black \&\ white image enhancement\\
 {\tt TVPSEUDO   } & Color enhancement of numerous sorts\\
 {\tt TVPHLAME   } & Color enhancement of flame type, multiple colors\\
 \Hi{{\tt OFMCOLOR }} & \Hi{Many standard color tables (OFMs)
                     available} \\
 {\tt TVZOOM     } & Interactive zooming and centering of image\\
 {\tt CURVALUE   } & Display value under cursor, mark pixels for list\\
\Hi{\tt BLOTCH LIST} & \Hi{Interactively add a blotch area to the pixel
                     list} \\
 {\tt NEXT WINDOW} & Move to next window into large images\\ \hline
\end{tabular}
\end{center}
Only one of the {\tt LOAD AS} options will appear, namely the next after
the current transfer function from the list of linear, square root, log,
and more extreme log transfer functions.  Most of the options are
familiar as {\tt AIPS} verbs.  Instructions for interaction will appear
on the terminal and button {\tt D} in the menu may be used to obtain a
helpful display on the terminal.

{\tt CURVALUE} provides the capability of selecting positions for the
edit ``list.'' During the {\tt CURVALUE} operation position the cursor
over the desired pixel and press buttons {\tt A}, {\tt B}, or {\tt C} to
add that pixel to the list. The \Hi{{\tt BLOTCH LIST} operation uses a
TV blotch operation like that in the \AIPS\ verb {\tt TVSTAT} and task
{\tt BLSUM}\@.  You are to mark with a ``blotch'' region those pixels
in the present image which are to be added to the list.  Instructions
will appear in the message window as you proceed.  Begin by positioning
the cursor at a pixel to be the first vertex of a connected sequence of
vertices and press TV button {\tt A}\@.  Move to the next vertex and
press button {\tt A} again and repeat until you have marked all vertices
for this region.  Then press button {\tt D} if you are done with this
region or button {\tt C} if you need to re-position one of the vertices.
In this case, move the cursor to the vertex to be re-positioned, press
button {\tt A} and drag the vertex to the corrected position.  Press
button {\tt A} or {\tt B} to fix that vertex and go on to reset another
vertex or {\tt D} to end this region.  You may do this as many times as
needed.}

\begin{figure}
\begin{center}
\resizebox{5.9in}{!}{\putfig{ZAMAN.e}}
\caption{\Hi{{\tt ZAMAN} image of field of component 1 ($B_1(y,z)$) with
  display options.}}
\label{fig:ZAMAN.field1}
\end{center}
\end{figure}

When you have finished getting the images just the way you want them,
you may write them out as \AIPS\ image files.  Select the {\tt SET
  DOOUTPUT} option until its value, shown at the top of the screen, is
what you want.  In {\tt ZEMAN}, values \Hi{4, 5, 6, 7, 12, 13, 14, and
  15 cause a residual (data-model) image cube to be written, values 2,
  3, 6, 7, 10, 11, 14, and 15 cause images of the gain and field values
  and their uncertainties to be written, values 1, 3, 5, 7, 9, 11, 13
  and 15} cause an image of the V cube to be written with the gain times
the I-polarization cube subtracted\Hi{, and finally values greater than
  7 cause an image of the residual rms to be written}.  The corrected
V-polarization image gets the class specified by {\tt OUTCLASS}, the
residual image gets class {\tt VRESID}, the gain and its uncertainty get
classes {\tt GAIN} and {\tt DGAIN}, and the field(s) and their
uncertainties get classes \Hi{{\tt FELD}$nBn$ and {\tt DFEL}$nn$, with
  $nn = 1$} to the maximum {\tt NGAUSS}\@.  \Hi{The residual rms image
  gets class {\tt RESRMS}\@.}
%\vfill\eject

\section{Post-fit plotting}

The images produced by {\tt XGAUS}, {\tt AGAUS}, {\tt ZEMAN} and {\tt
  ZAMAN} may be displayed using all the usual tools such as {\tt
  KNTR}, {\tt PROFL}, and numerous other tasks.  However, the display
of the spectral data and the various fits to them required a new task.

\begin{figure}
\begin{center}
\resizebox{6.2in}{!}{\putfig{XG2PL.a}}
\centerline{\hphantom{MM}}
\resizebox{6.2in}{!}{\putfig{XG2PL.b}}
\caption{\Hi{Example spectra from two single pixels for fits done by
    {\tt AGAUS} and {\tt ZAMAN}.  Data are in yellow, models in green,
    and residuals in pink.}}
\label{fig:XG2PL.agaus}
\end{center}
\end{figure}

{\tt XG2PL} plots a spectrum for a single pixel or for a rectangular
or circular region about a single pixel.  For each pixel included in
the average, the task reads the I polarization image to obtain the
data and the appropriate row in the {\tt XG} table to obtain the {\tt
  AGAUS} solution for that pixel.  It then computes the spectrum of
each component in the model, plus the sum of the components, and the
residual (data-model).  Each of these then enter into the average of
that parameter.  Finally, the task plots a user-selected number of the
parameters and, optionally, prints all of them to a text file.  The
plot may appear on the TV or be placed in a standard plot file
attached to the I polarization image.

Optionally, {\tt XG2PL} will also add the spectrum of the V
polarization data and the results of the fitting done by {\tt ZEMAN}
or {\tt ZAMAN} at the same pixels as the I polarization Gaussians.
The task reads the V polarization image for the data spectrum and
the {\tt ZE} table for the Zeeman-splitting model (either using the
Gaussians or the simpler ones using the I polarization data).  It
computes the spectrum of each component (including the gain term in
each), the net model (sum of the components but including the gain
term only once), and the residual.  Finally, the task plots a
user-selected number of the parameters and, optionally, prints all of
them to a text file.  In general, the I polarization spectrum appears
in the upper part of the plot and the V polarization spectrum appears
in the lower portion. Either portion may be omitted under control of
the adverbs.  The output of {\tt XG2PL} is illustrated in
Figure~\ref{fig:XG2PL.agaus} for the absorption model \Hi{at each
  ``source''.}

The inputs for {\tt XG2PL} begin with the I polarization image which
is required and then the V polarization image which may be omitted.
{\tt INVERS} and {\tt IN2VERS} give the version numbers of the {\tt
  XG} and {\tt ZE} tables, respectively.  {\tt APARM} provides the
central pixel coordinates, the plot intensity ranges for I and for V,
the size of the rectangle (or circle) over which to average, and a
flag limiting the average to those pixels having a model fit,  {\tt
  BPARM} is a set of flags selecting which parameters are plotted.
{\tt CPARM} selects the channel range to be plotted, the relative size
of the V and I plots, the type of the horizontal axis (channels,
frequency, velocity), whether the channels are plotted in reverse
order, and whether the data are plotted with stepped or directly
connected lines.  For absorption models, {\tt CPARM} also offers the
option of plotting the I spectra as optical depth rather than as
observed.  {\tt OUTTEXT} specifies the output text file, if any.  The
usual {\tt XYRATIO}, {\tt LTYPE}, {\tt DOTV}, and {\tt GRCHAN} adverbs
control the scale, labeling, choice of TV versus plot file, and, if
TV, which graphic channel(s) are used.  If {\tt GRCHAN} is zero,
graphics channel 1 is used for data and labeling (usually yellow),
channel 2 is used for the full model (usually green), channel is used
for the residual (usually pink), and channel 4 is used for the model
component(s) (usually cyan).

\section{Image model creation}

\AIPS\ Memo 118 describes a wide variety of modeling tasks which will
not be discussed here.  A new, simplified task was written to provide
direct studies of the fitting in {\tt XGAUS}, {\tt AGAUS}, {\tt
  ZEMAN}, and {\tt ZAMAN}\@.

The new task is called {\tt MODAB} and has a small number of adverbs.
{\tt COORDINA}, {\tt CELLSIZE}, {\tt APARM(1)}, and {\tt APARM(2)} set
image header parameters with values that are not otherwise used.  {\tt
  IMSIZE} and {\tt CPARM(3)} set the size of the image cube in
pixels.  {\tt APARM(4)} through {\tt APARM(9)} define a Gaussian which
is the continuum ``source'' when imaging in absorption or is used to
scale the emission as a function of position when making an emission
cube.  {\tt APARM(10)} defines the fractional leakage of the I
polarization into V and {\tt FLUX} sets the noise level in Jy/beam.
{\tt OPTYPE = 'EMIT'} requests an emission cube, otherwise an
absorption cube is produced.

A text file, pointed at with {\tt INLIST} contains up to 99 spectral
features to be spread over the cube.  Each line must contain
\begin{center}
\begin{tabular}{|r|l|}\hline
 1. & Central optical depth (unitless) or peak brightness (Jy/beam)\\
 2. & Central spectral channel (pixels)\\
 3. & Full width of line at half-maximum (pixels)\\
 4. & Separation of R and L polarization in channels (pixels)\\\hline
\end{tabular}
\end{center}

\section{Systematic errors}

\begin{figure}
\begin{center}
\resizebox{6.0in}{!}{\putfig{PLOTR.model10}}
\caption{Measured relative widths ($s/\sigma$) in green and splittings
  ($s/\sigma$) in red plotted against the model splitting
  $\delta/\sigma$.}
\label{fig:PLOTR.model}
\end{center}
\end{figure}

The image model task described above was used in both emission and
absorption with high signal-to-noise to check for ``systematic
errors'' in the answers returned by {\tt XGAUS}, {\tt AGAUS}, {\tt
  ZEMAN} and {\tt ZAMAN}\@.  The I polarization Gaussian width, not
surprisingly, is measured to be wider than $\sigma_i$ since the
emission profile is widened by the splitting due to the magnetic
field.  The quality of the fit to a Gaussian also deteriorates as the
emission line becomes less Gaussian in shape when the splitting
becomes significant with respect to the unsplit line width.  The
measured splitting in V polarization is computed via
Equation~\ref{eqn:ZemanGaus} and so would appear to suffer from the
bias in the measured $\sigma_i$ squared.  Experimentation with the
modeling tasks shows, however, that the bias in the splitting is
almost the same (fractionally) as in the width.  A variety of model
separations ($\delta$) were tried at several fixed component widths
($\sigma$) with very good signal-to-noise.  The apparent Gaussian
full-widths at half maximum ($s$) were measured with {\tt XGAUS} and
the apparent Zeeman splittings ($d$) were measured with {\tt ZEMAN}\@.
When plotted as relative widths ($s/\sigma$) and relative separations
($d/\sigma$) against $\delta/\sigma$, as in
Figure~\ref{fig:PLOTR.model}, the curves for the tested values of
$\sigma$ were approximately the same.  The plotted fits to the curves
in Figure~\ref{fig:PLOTR.model} are given by
\begin{eqnarray}
  s/\sigma & = & 1.0 - 0.010 (\delta/\sigma) + 0.7485
                 (\delta/\sigma)^2 \\
  d/\sigma & = & 1.0 - 0.002 (\delta/\sigma) + 0.6827
                 (\delta/\sigma)^2
\end{eqnarray}
with an rms of the fit of about 0.0002.

Note a certain difficulty with these formul\ae.  Users of {\tt XGAUS},
{\tt AGAUS}, {\tt ZEMAN} and {\tt ZAMAN} will obtain values of $s$ and
$d$ and will have to find $\delta$ and $\sigma$ by some inverse
method.  Note too that, while doing these tests, some rather abnormal
values were found, especially for $d$, despite the rather good
signal-to-noise.  It may be advisable to use the {\tt MODAB} modeling
task to simulate your data in order to determine the real
uncertainties and systematic errors which apply.

\end{document}

