%-----------------------------------------------------------------------
%;  Copyright (C) 2016-2017, 2019, 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.6,0.05,0.05}
\definecolor{mecol}{rgb}{0.1,0.1,0.6}
\definecolor{excol}{rgb}{0.05,0.5,0.05}
\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{\putfig}[1]{\includegraphics{#1}}
\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}{120 \Hi{Revised}}
\newcommand{\memtit}{Exploring Image 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\ has recently acquired powerful tasks to fit models to the
  spectral axis of image cubes.  These tasks are easier to run if the
  user is already familiar with the general structure of the data
  cube.  A new task {\tt TVSPC} has been written to assist in
  acquiring this familiarity.  This task provides an exploration tool
  within the \AIPS\ environment, rather than requiring users to export
  their cubes to one or more of the many excellent visualization tools
  now available.  In the {\tt 31DEC17} version an additional data
  cube may be displayed one plane at a time.  \footnote{The color
  \Hi{red} has been used for changes made to this memo in April 2025;
  all other coloring for earlier revisions has been removed.}
\end{abstract}

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

\section{Introduction}

A completely re-written {\tt XGAUS}, plus new tasks {\tt ZEMAN} and
{\tt RMFIT} first appeared in the {\tt 31DEC13} release of \AIPS\ and
have been improved in subsequent releases.  {\tt XGAUS} fits Gaussians
to the first axis of an image cube, normally the spectral axis of a
transposed cube.  {\tt ZEMAN} fits a gain and one or more parameters
proportional to magnetic field to matching cubes of total (Stokes I)
polarization and circular (Stokes V) polarization.  {\tt RMFIT} fits
Faraday rotation and thickness models to matching cubes of linear
polarization (Stokes Q and U)\@.  These tasks, along with display and
modeling tasks, are described in an \AIPS\ Memo\footnote{Greisen,
  E.W. 2015, \AIPS\ Memo 118 revised, ``Modeling Spectral Cubes in
  \AIPS,'' May 2020 revision.} which includes descriptions of the
mathematics, the input adverbs, and the flow of each program.
Similar tasks geared for use with absorption-line spectral cubes
have appeared in the {\tt 31DEC17} release of \AIPS\@.  {\tt AGAUS} and
{\tt ZAMAN} are also described in an \AIPS\ Memo\footnote{Greisen,
E.W. 2017, \AIPS\ Memo 122, ``Modeling Absorption-line Cubes in \AIPS,''
May 2020 revision.}

One can use the above tasks without being familiar with the contents
of the image cubes.  However, users who are familiar with the contents
of their data cubes will find the modeling tasks simpler to use.  The
author has watched \AIPS\ users export their cubes (with {\tt FITTP})
to the various external image viewers now available.  While \AIPS\
cannot attempt to duplicate the full functionality of these excellent
tools, it can offer, within the \AIPS\ environment, some tools to
acquaint the user with the contents of the image cube(s).  In addition
to the task {\tt TVSPC} described herein, there is another new task {\tt
TVIEW} described in another \AIPS Memo.\footnote{Greisen, E. W. 2019,
\AIPS\ Memo 124, ``Further Exploration of Image Cubes in \AIPS'',
April 2025 (revised).}  It displays image cubes in all three
transpositions with a reference image and a spectral plot.


\section{Spectral exploration: {\tt TVSPC}}

A new task, called {\tt TVSPC}, has now appeared in the {\tt 31DEC16}
version of \AIPS, with added options in \Hi{later versions}.  It
presumes that the user has a ``spectral'' image cube which has been
transposed to make the spectral axis first and the two spatial
coordinates as the second and third axes.  Optionally, the user may
also have a second transposed spectral cube which matches the first in
its dimensions and coordinates.  {\tt XGAUS} requires a transposed
cube, while transposed-cube pairs are required by {\tt ZEMAN} (Stokes
I and V) and by {\tt RMFIT} (Stokes Q and U) already.  {\tt TVSPC}
also assumes that the user has some ``reference image,'' namely an
image plane (in the spatial axes) that represents the emission region
as a whole.  This reference image may be a moment-zero image from a
normal spectral-line cube, the Stokes I image from a region of
polarized emission, or any other two-dimensional image meaningful to
the user.  The reference image does not need to have the same
dimensionality or coordinates as the cube(s) so long as they all
overlap in the spatial coordinates.  The {\tt 31DEC17} version of
{\tt TVSPC} introduces an optional ``spatial'' cube in the
transposition having the spatial axes first followed by the spectral
axis.  This cube may be displayed interactively, one plane at a time,
and also used to select spectra from the transposed cube(s).  This
cube must have the same spectral coordinate type and similar spatial
coordinate types as the transposed cube(s), but is not required to
have the same reference values, increments, or pixels as those cubes.

\subsection{Inputs}

The usual {\tt INNAME} {\it et al.} adverbs define the two-dimensional
reference image to be loaded as a gray-scale image on the \AIPS\ TV
(assumed to be the {\tt XAS} program).  Adverbs {\tt TBLC} and {\tt
  TTRC} select the portion of the image to appear on the TV including
the plane if {\tt INNAME} points at an image cube.  {\tt TVCHAN}
selects the TV channel used for the gray-scale display. {\tt PIXRANGE}
selects the image intensity range while {\tt FUNCTYPE} selects the
transfer function used to load the image to the TV\@.  {\tt IN2NAME}
{\it et al.} adverbs define the primary transposed spectral cube to be
examined.  Optionally, the {\tt IN3NAME} {\it et al.} adverbs define
the secondary spectral cube to be explored along with the first.  Two
spectra are displayed if {\tt IN3NAME} is specified, otherwise only
one spectrum is shown.  If {\tt IN4NAME} {\it et al.} adverbs are
also specified, then the menu includes options to display the spatial
cube.  Adverb {\tt CBPLOT} controls the plotting of the Clean beam
on position-position images when labeling is enabled.

Adverbs {\tt APARM} and {\tt SAMPTYPE} control the plotting of the
spectra and may be changed interactively.  {\tt APARM(1)} and {\tt
  APARM(2)} control the plotted range of the spectra, with {\tt
  APARM(2) $>$ APARM(1)} setting a fixed scale, {\tt APARM(2) $<$
  APARM(1)} selecting the full image range, and {\tt APARM(2) $=$
  APARM(1)} having each plot be self-scaling.  The spectra plotted are
the average of the cube over a circular aperture (in the $y-z$ axes)
of radius {\tt APARM(3)} pixels with zero meaning a single pixel.  The
gray-scale image(s) and the spectra may appear in the right and left
halves of the screen ({\tt APARM(4)} $> 0$), they may appear in the
upper and lower halves of the screen ({\tt APARM(4)} $< 0$), or they
may appear on top of each other ({\tt APARM(4)} $= 0$) using the full
screen area.  When the screen is split, {\tt APARM(5)} controls the
fraction used by the spectra.  If {\tt IN3NAME} is specified, the two
spectral plots may appear on top of each in separate colors but the
same intensity range ({\tt APARM(6)} $\leq 0$) or be separated into
two, potentially differently-scaled plots.  If the spectra are in the
lower half of the screen, this separation is horizontal.  Otherwise it
is vertical.  Spectra are labeled in channels if {\tt APARM(8) > 0},
otherwise they are labeled in the units of the first axis of the
transposed cube.  When doing Gaussian fits, {\tt APARM(9)} controls
the fitting of a spectral baseline.  A value of zero means no
baseline, one fits a constant, two fits a constant and a slope, and
three fits a constant, a slope and a second-order term.

The spectra, after they have been read from the transposed cube(s) and
averaged, may also be smoothed spectrally.  If {\tt SAMPTYPE} is
{\tt 'BOX'} (boxcar) or {\tt 'MWF'} (median-window), {\tt APARM(7)}
specifies the number of spectral pixels over which the boxcar or
median-window is performed.  If {\tt SAMPTYPE} is {\tt 'HANN'}
(Hanning), {\tt 'GAUS'} (Gaussian), or {\tt 'EXP'} (exponential), {\tt
  APARM(8)} is the full-width at half maximum of these functions in
spectral pixels.  All other values of {\tt SAMPTYPE} produce no
spectral smoothing.  It has been found that {\tt 'MWF'}, while very
useful for removing badly discrepant points from \eg\ RFI, produces
less than desirable results when applied to well-behaved spectra.

Note that the values of {\tt APARM}, {\tt CBPLOT}, and {\tt SAMPTYPE}
may be changed interactively during the execution of {\tt TVSPC}\@.

\subsection{Execution: the image}

When {\tt TVSPC} begins, it loads the TV in gray-scale with the
reference image from {\tt INNAME} with the plane selected by {\tt
  TBLC} and {\tt TTRC} and the scaling selected by {\tt PIXRANGE} and
{\tt FUNCTYPE}\@.  If the spatial cube is not specified, the image is
centered in the full screen, the left half of the screen, or the upper
half of the screen, depending on {\tt APARM(4)}\@.  Whenever the
reference image is loaded to the screen, the pixel increment in $x$
and $y$ is made the same and is chosen to maximize the size of the
displayed image.  Thus every $n^{\rm th}$ pixel may be loaded, every
pixel may be loaded, or an interpolated image may be loaded.  A
message telling the pixel increment or interpolation factor appears in
the message window.  If the spatial cube is specified ({\tt IN4NAME}
{\it et al.} set), then the reference image is shown in left half of
the area used for grey-scale images or the lower half if {\tt APARM(4)
  > 0}.

The following menu appears in yellow at the left of the screen
whenever you need to select some operation.

\begin{center}
\begin{tabular}{|l|l|}\hline
 {\tt OFF TRANS      } & Initialize black-and-white transfer function \\
 {\tt OFF PSEUDO     } & Turn of any pseudo-coloring \\
 {\tt TVTRANSF       } & Adjust black-and-white transfer function \\
 {\tt TVPSEUDO       } & Color contours of a variety of types \\
 \Hi{{\tt TVPHLAME  }} & Flame-like pseudo-coloring \\
 \Hi{{\tt OFMCOLOR  }} & \Hi{Pseudo-colorings from many OFM tables} \\
 {\tt SET APARM      } & Change the plot and smoothing parameters \\
 {\tt LABEL IMAGES?  } & Cycle through image labeling options \\
 {\tt                } & \\
 {\tt SET WINDOW     } & Select a sub-image for more detailed viewing \\
 {\tt RESET WINDOW   } & Return to viewing full image \\
 {\tt SET CHANNELS   } & Interactively set channel range for spectra \\
 {\tt RESET CHANNELS } & Plot and fit spectra with all channels \\
 {\tt CURVALUE       } & Display intensity and pixel under the cursor\\
 {\tt PLOT SPECTRA   } & Plot spectra of cube(s) selected with
                         reference image  \\
 {\tt FIT SPECTRUM   } & Gaussian fit the plotted spectrum \\
 {\tt SAVE SPECTRUM  } & Save the plotted spectrum as a slice \\
 {\                  } & \\
 {\tt LOAD PLANE     } & Display a plane selected from the spatial cube \\
 {\tt PLOT PL SPECTRA} & Plot spectra of cube(s) selected with plane
                         from spatial cube\\
 {\tt SET PL WINDOW  } & Select a sub-image from the spatial cube plane \\
 {\tt RESET PL WIN   } & Return to viewing the full spatial cube
                         plane\\
 {\tt SET PL RANGE   } & Enter intensity range for spatial cube display\\
 {\                  } & \\
 {\tt EXIT           } & Exit {\tt TVSPC}\\ \hline
\end{tabular}
\end{center}

The gray-scale image(s) are displayed with a black-and-white
enhancement function followed by pseudo coloring, all with familiar
functions.  {\tt TVTRANSF} is an interactive alteration of the
black-and-white enhancement in which the TV cursor $x$ position
controls the intercept and the $y$ position controls the slope of a
linear transfer function.  Buttons A and B turn a plot of this
function on and off, button C changes the sign of the slope, and
button D exits.  {\tt OFF TRANS} resets the transfer function.  {\tt
  TVPSEUDO} is an interactive pseudo coloring.  Button A selects
triangles in the three colors with the cursor $x$ position controlling
the position separating the lowest color from the highest, the cursor
$y$ position controls the ``gamma'' correction affecting the intensity
of the colors, and repeated hits of button A cycling between all 6
possible color orders.  Button B selects circles in hue at maximum
saturation and intensity, with the cursor $x$ position controlling the
number of circles and the cursor $y$ position controlling the starting
hue.  Button C selects color contours with the cursor $x$ position
controlling the image intensity at which contours begin, the cursor
$y$ position sets the range of image intensities over which the
contours extend, and repeated hits of button C select between five
different contour designs.  Button D exits, returning to read the next
operation from the menu.  \Hi{{\tt TVPHLAME}} implements a flame-like
pseudo-coloring ranging initially from red through orange and yellow
to white.  The cursor $x$ position controls the intensity at which the
color transitions take place, the $y$ position controls the gamma
correction and repeated hits of buttons A or B will cycle between the
6 color sequences possible.  Buttons C and D return you to the main
menu.  \Hi{{\tt OFMCOLOR}, added in version {\tt 31DEC25}, allows you to
set the color transfer function using the TV cursor and a large number
of the standard OFMs (``output function memory'' tables).  Hitting
buttons A, B, or C causes the selected OFM to change working through 3
separate lists of 10.  After an OFM has been selected it may be adjusted
with the horizontal position of the cursor.  Hit button D to exit,
keeping whatever color scheme you have developed.}  {\tt OFF PSEUDO}
turns off all coloring.

{\tt SET WINDOW} is used to select a section of the reference image to
be blown up for more detailed pixel selection.  It is similar to verb
{\tt TVWINDOW} and begins by setting the lower-left corner.  Hit
buttons A or B to switch to setting the upper right corner.  Buttons A
and B switch between the corners thereafter.  Buttons C and D exit
with the window set.  At this point, {\tt TVSPC} reloads the
reference image with the selected corners, maximizing the size of the
image on the TV while keeping the $x$ and $y$ pixel increments the
same.  {\tt RESET WINDOW} sets the display corners back to the initial
{\tt TBLC} and {\tt TTRC} and reloads the reference image with the
pixel increment that maximizes the size of the image on the TV.

{\tt SET APARM} carries out a dialog on the input terminal to change
all of the {\tt APARM} and {\tt SAMPTYPE} adverb values.  The task
prompts with ``Spectral plot range min and max.''  Enter 2 values: if
the first is less than the second the spectral plots are done from the
first value to the second, if the second is greater than the first the
spectral plots are done over the full image range, and if the first
equals the second the spectral plots are all self-scaling.  The
task then prompts ``Spectral averaging radius in YZ pixels;'' enter 1
value $>= 0$ to set the spatial averaging radius in {\tt IN2NAME}
$y-z$ pixels.  Then the task prompts ``Split screen: $< 0$ vertical,
$> 0$ horizontal, 0 none'' to set the split of the screen between the
area for the {\tt INNAME} (and {\tt IN4NAME}) image(s) and the area
for the spectral plot(s).  If a split screen is selected, the prompt
``Fraction of split screen for spectra'' requests a number between 0.1
and 0.9 with a default of 0.5.  If {\tt IN3NAME} was specified, you
are asked ``Split spectra: $<= 0$ no, $> 0$ yes'' to control whether
the two spectra over-plot each other or plot in separate windows.
Then the question ``Baseline fit order: > 0 -> yes'' appears.  Answer
0 for no baseline or 1, 2, or 3 for the number of polynomial parameters
to be fit.  Finally, the prompt ``Spectral smoothing function type (4
characters)'' requests a string to do spectral smoothing, with {\tt
  BOX}, {\tt MWF}, {\tt HANN}, {\tt GAUS}, and {\tt EXP} as known
values.  Any other value means do not smooth spectra.  If smoothing
with {\tt BOX} or {\tt MWF}, you are prompted for ``Spectral smoothing
support in channels'' or, if smoothing with {\tt HANN}, {\tt GAUS}, or
{\tt EXP}, you are prompted with ``Spectral smoothing FWHM in
channels.''.  Enter one number greater than zero for the full support
or FWHM in channels.  Finally, you are prompted for ``Set CBPLOT to
  0 to 4.''  Enter 0 for no Clean beam plot, 1 lower left corner, 2
  lower right, 3, upper right, or 4 upper left.

The {\tt LABEL IMAGES?} option has three states: labels off, labels on
the gray-scale image(s), and labels on the image(s) with a full
coordinate grid.  Successive selection of this option cycles through the
three states.  The {\tt CURVALUE} option lets you display the pixel
numbers and intensity under the cursor when the cursor is placed in one
of the grey-scale images and when the cursor is placed in one of the
spectral plots.  In the latter, the intensity displayed is that of the
particular spectrum at the channel selected by the cursor rather than
the value actually under the cursor.

\subsection{Execution: spectra}

The purpose of {\tt TVSPC} is to examine spectra, but until {\tt PLOT
  SPECTRA} is selected the portion of the screen reserved for spectral
plots is blank.  Selecting this option, position the TV cursor within
the reference image and move it around.  The TV cursor selects a
celestial position, the spectra at that position are read from the
transposed cube(s) and averaged over radius {\tt APARM(3)} pixels,
smoothed spectrally if requested, and then plotted.  Note that, if two
spectra are plotted, both have been averaged over the same area and
smoothed spectrally in the same manner.  The position and intensity of
the reference (gray-scale) image are tracked in the upper left corner
of the screen (much like verb {\tt CURVALUE}) while the spectral
plot(s) display the celestial coordinate and transposed-image pixel
position along with the plot(s).  Move the cursor around to select
some particularly interesting spectrum.  Then hit buttons C or D to
terminate the plotting.  Pixel positions not in the transposed image
are reported whenever such errors begin.

Initially, the spectra are plotted with all spectral channels found in
the transposed cubes.  However, having exited from {\tt PLOT SPECTRA},
you may select the {\tt SET CHANNELS} option which will allow you to
reduce the range of channels plotted and used in the fitting described
below.  {\tt SET CHANNELS} is interactive.  It plots a vertical line at
each end of the plotted spectrum and then reads the cursor to adjust
these end points.  Buttons A and B allow you to switch between the
lower and upper end points while the channels chosen are displayed in
the upper left of the screen.  When you hit buttons C or D, the
channel range is set and will be used in future executions of {\tt
  PLOT SPECTRA}\@.  The {\tt RESET CHANS} option is the only way to
select a channel range outside the current range and it sets the
channels to the full range.  Thus to choose a restricted range outside
the current range, you must {\tt RESET CHANS}, then {\tt PLOT
  SPECTRA}, and finally {\tt SET CHANNELS}\@.

Having exited from {\tt PLOT SPECTRA}, you may choose to fit up to
four Gaussians to the spectrum from {\tt IN2NAME}.  Select {\tt FIT
  SPECTRUM} and the task will prompt you to position the cursor at the
peak of the first component and hit button A or B.  This sets the
initial guess for the peak and central channel of the first component.
Then the task prompts you to point at the half-power point of the
first component and hit button A or B.  The $x$ position of the cursor
then sets the initial guess of the FWHM of the first component.  The
task then asks for the initial guesses for component 2, 3, and 4 in a
similar fashion.  If at any time you hit buttons C or D, the setting
of the initial guesses is terminated and the number of Gaussians fit
will be the number for which both positions were specified.  The task
then fits the Gaussians to the spectrum, including an optional
polynomial baseline, using non-linear least squares (as in {\tt SLFIT}
and {\tt XGAUS})\@.  The results including uncertainties are displayed
on the message terminal with the peaks being in image brightness units
and the centers and widths being in channels.  The task plots the
model fit and the residuals (data minus model) in two additional
colors on top of the spectrum.  If the result is not satisfying, you
may select {\tt FIT SPECTRUM} and try a new initial guess.  Note that
selecting {\tt PLOT SPECTRA} causes the Gaussian fit results to be
discarded.

Having exited from {\tt PLOT SPECTRA}, you may choose to save the
displayed spectrum as a slice ({\tt SL}) file attached to its
transposed spectral cube ({\tt IN2NAME})\@.  The full spectrum is
saved as a slice with the necessary additional information to match
the action that could have been done by task {\tt SLICE}, but with the
addition of the optional spatial averaging and spectral smoothing.
The latest Gaussian fit, if any, is also saved with the slice in a
manner matching that of task {\tt SLFIT}\@.


\subsection{Execution: spatial cube}

A third ``spatial'' cube may be specified with adverbs {\tt IN4NAME}
{\it et al.}  If it has been specified, additional menu items appear.
Having done a {\tt PLOT SPECTRA}, you may now do a {\tt LOAD PLANE}\@.
This operation displays a vertical line in the spectrum plot which is
used to select the spectral value of a plane from the spatial cube.
This plane is then displayed in the right-hand or upper half of the area
reserved for grey-scale displays.  Moving the cursor horizontally in the
spectral plot allows you to select planes quite interactively.  When
you have found a plane you wish to examine in more detail, hit any
button to terminate the {\tt LOAD PLANE} operation.

Having displayed a plane from the spatial cube, you may now {\tt
PLOT PL SPECTRA} which is the same operation as {\tt PLOT SPECTRA} but
using the displayed plane from the spatial cube.  You may also {\tt
  SET PL WINDOW} which is the same as {\tt SET WINDOW} except that it
sets a window into the spatial cube.  That window will be used for the
current display and any further {\tt LOAD PLANE} operations until a
{\tt RESET PL WIN} resets the spatial cube window to the full
dimensions of the cube.  The intensity range used for the spatial cube
grey-scale display may be changed with {\tt SET PL RANGE}\@.  Enter
two numbers, the lower end of the range followed by the upper end of
the range.  If the second number entered is less than or equal the
first, then the full intensity range of the spatial cube will be
displayed.  The prompt message shows that full range of intensities.

\subsection{Examples}

The first example is an HI spectral line cube of NGC 6503.  The
reference gray-scale image chosen is a moment-zero image giving a
wide-angle view of the total HI in the galaxy.  It covers a larger
spatial area than the transposed cube which also has different spatial
pixel size and other different coordinate parameters.
Figure~\ref{fig:HIab} illustrates the split screen option, with the
top plot having {\tt APARM(4) = -1} and the bottom plot having {\tt
  APARM(4) = 1}\@.  The gray-scale image is loaded over its full range
in the top plot, but only every other pixel.  In the bottom plot, {\tt
  SET WINDOW} was used to allow every pixel in the sub-image to fit in
the left 45\%\ of the screen.  In the bottom plot, the {\tt PLOT
  SPECTRA} operation is being performed, giving the {\tt
  CURVALUE}-like display in the upper left corner.

Figure~\ref{fig:HIcd} also illustrates the split screen option, with
the top plot having {\tt APARM(4) = 1} and the bottom plot having {\tt
  APARM(4) = 0}\@.  Every pixel of a large sub-image of the moment
zero image is loaded in the top plot, while a smaller sub-image allows
the loading ``interpolated by 4'' (meaning 3 values interpolated
between every actual image pixel).  In both, a Gaussian fit has been
performed.

Figure~\ref{fig:HIeg} illustrates the {\tt 31DEC19} \Hi{and later}
versions with a spatial cube specified.  Note the presence of 5
additional menu items.  The reference image is the moment-zero (total
HI) image while the spatial cube is the spectral cube before
transposition.  The top plot shows the screen after a {\tt PLOT SPECTRA}
but before any {\tt LOAD PLANE}\@.  The bottom shows the screen after a
{\tt LOAD PLANE} operation was performed.  The vertical pink line in the
spectrum plot shows the plane chosen.

The second example is of a small OH maser region with spectral cubes in
both Stokes I and Stokes V\@.  In these data, the two maser lines were
not spatially resolved, although {\tt ZEMAN} following {\tt XGAUS} was
able to determine separate magnetic field strengths for the two
components.  Lacking a moment-zero image, we use one of the output
images from {\tt ZEMAN} (the ``field1'' image).  Figure~\ref{fig:OHab}
shows screens split vertically ({\tt APARM(4) = -1}) with the top
image not separating the I and V spectra ({\tt APARM(6) = 0}) and the
bottom plot separating them ({\tt APARM(6) = 1})\@.  In the top plot,
the {\tt PLOT SPECTRA} operation is being performed, leading to the
{\tt CURVALUE}-like display in the upper left corner.  Note the units
of the field1 image.  In the bottom plot, the Stokes I spectrum has
been fit with two Gaussians and a small sub-image was selected in
order to see some detail in the field1 image.  Both plots used {\tt
  APARM(5)=0.6} to increase the size of the spectral plots.

Figure~\ref{fig:OHcd} illustrates screen splitting with the full
screen split horizontally and the spectra vertically ({\tt APARM(4) =
1} and {\tt APARM(6) = 1})\@. in the top plot.  In the bottom plot,
both splits have been turned off ({\tt APARM(4) = 0} and {\tt
APARM(6) = 0}).  In each plot, the Stokes I spectrum has been fit
with two Gaussians.

Figure~\ref{fig:QUab} illustrates the use of {\tt TVSPC} with full
polarization cubes.  The total intensity image is shown with spectra
from Stokes Q and U.

The HI data have been described in the literature by Greisen, E. W.,
Spekkens, K., van Moorsel, G. A., 2009, ``Aperture Synthesis
Observations of the Nearby Spiral NGC 6503: Modeling the Thin and
Thick Disks,'' AJ, 137, 4718-4733.  The OH data were provided by
Emmanuel Momjian from EVLA commissioning observations of sources known
to show Zeeman splitting.  The polarization data were produced by
an \AIPS\ simulation task to test rotation-measure modeling in {\tt
  RMFIT}\@.

\begin{figure}
\begin{center}
\resizebox{5.98in}{!}{\putfig{TVSPCHIa.eps}}
\centerline{\hphantom{MM}}
\resizebox{5.98in}{!}{\putfig{TVSPCHIb.eps}}
\caption{HI moment-zero reference image with spectrum.  Top: split
  vertically, every other pixel of reference image loaded, shown with
  flame coloring at the menu prompt.  Bottom: split horizontally,
  every pixel of sub-image loaded, shown during {\tt PLOT SPECTRA}
  operation.}
\label{fig:HIab}
\end{center}
\end{figure}

\begin{figure}
\begin{center}
\resizebox{5.98in}{!}{\putfig{TVSPCHIc.eps}}
\centerline{\hphantom{MM}}
\resizebox{5.98in}{!}{\putfig{TVSPCHId.eps}}
\caption{HI moment-zero reference image with spectrum.  Top: split
  horizontally, every pixel of reference sub-image loaded, shown at
  menu prompt after {\tt FIT SPECTRUM} and {\tt LABEL IMAGES?}\@.
  Bottom: not split, smaller sub-image interpolated by 4, shown at
  menu prompt after {\tt FIT SPECTRUM} operation.}
\label{fig:HIcd}
\end{center}
\end{figure}

\begin{figure}
\begin{center}
  \resizebox{5.75in}{!}{\putfig{TVSPCHIe.eps}}
\centerline{\hphantom{MM}}
\resizebox{5.75in}{!}{\putfig{TVSPCHIg.eps}}
\caption{HI moment-zero reference image with spectrum and spatial
  cube.  Top: split vertically, every pixel of reference sub-image
  loaded, shown at the menu prompt before {\tt LOAD PLANE}\@.  Bottom:
  same image, shown after {\tt LOAD PLANE} and {\tt TVPSEUDO} with every
  pixel loaded from a sub-image of a plane of the spatial cube.  The
  intensity range of the plane has been set to 0 to 0.01 Jy/beam from
  the default -0.003 to 0.017 Jy/beam.  Image axes are labeled.
  Sub-images are shown so that the Clean beam ({\tt CBPLOT=4}) will be
  visible.}
\label{fig:HIeg}
\end{center}
\end{figure}

\begin{figure}
\begin{center}
  \resizebox{6.0in}{!}{\putfig{TVSPCOHa.eps}}
\centerline{\hphantom{MM}}
\resizebox{6.0in}{!}{\putfig{TVSPCOHb.eps}}
\caption{OH ``field1'' reference image with I and V spectra, screen
  split vertically.  Top: every pixel of image loaded, shown during
  {\tt PLOT SPECTRA} operation with I and V spectra overlapped.
  Bottom: sub-image interpolated by 7 loaded, spectra averaged over
  radius of 1 pixel, shown at menu prompt with I and V spectra
  separated and image labeled.}
\label{fig:OHab}
\end{center}
\end{figure}

\begin{figure}
\begin{center}
\resizebox{6.0in}{!}{\putfig{TVSPCOHc.eps}}
\centerline{\hphantom{MM}}
\resizebox{6.0in}{!}{\putfig{TVSPCOHd.eps}}
\caption{OH ``field1'' reference image with I and V spectra shown
  after {\tt FIT SPECTRUM} operation.  Top: split horizontally with
  {\tt APARM(5)=0.6}, sub-image loaded interpolated by 14, could now
  save spectrum as a slice.  \Hi{One of the {\tt OFMCOLOR}s was
  chosen. Bottom: not split, sub-image interpolated by 23, spectra
  averaged over radius of 1 pixel, shown at menu prompt with a fit
  at a point off center.}}
\label{fig:OHcd}
\end{center}
\end{figure}

\begin{figure}
\begin{center}
\resizebox{5.46in}{!}{\putfig{TVSPCQUa.eps}}
\centerline{\hphantom{MM}}
\resizebox{5.46in}{!}{\putfig{TVSPCQUb.eps}}
\caption{The third example is a model reference image made to test {\tt
    RMFIT}\@.  The gray-scale is the Stokes I image and the transposed
  cubes are the Stokes Q (green) and U (pink) images.  The screen is
  split horizontally with different values of {\tt APARM(5)} and the
  polarized spectra are split vertically.  The screen shots were taken
  during a {\tt PLOT SPECTRA} operation at different pixels in the
  upper model object.  The gray-scale image was interpolated by 5 in
  the upper plot and by 3 in the lower plot.  The spectra were averaged
  over a radius of 2 in the upper plot and not averaged in the lower
  plot.}
\label{fig:QUab}
\end{center}
\end{figure}

\end{document}
