\documentclass[11pt]{book}
\usepackage{natbib}
\include{gildas-def} % GILDAS specific definitions

\makeindex{}

\newcommand{\lang}[1]{\texttt{\MakeUppercase{#1}$\backslash$}}

\newcommand{\lmv}{\texttt{lmv}}
\newcommand{\clean}{\texttt{CLEAN}}
\newcommand{\uv}{$uv$}
\newcommand{\emm}[1]{\ensuremath{#1}}   % Ensures math mode.
\newcommand{\emr}[1]{\emm{\mathrm{#1}}} % Uses math roman fonts.
\newcommand{\nds}[1]{\emm{\displaystyle#1}} % Normal display size for array and tabular environment.
\newcommand{\paren}[1]  {\nds{\left(  #1 \right) }} % Parenthesis. 
\newcommand{\cbrace}[1] {\nds{\left\{ #1 \right\}}} % Curly Braces.
\newcommand{\abs}[1]{\emm{\left| #1 \right|}} % Absolute value.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{document}

\frontmatter{} %

\begin{center}
  \huge{}
  \textbf{MAPPING} \\[2\bigskipamount]
  \Large{}
  A \gildas{} software\\[\bigskipamount]
  March 29th, 2007\\[\bigskipamount]
  Version 2.0\\[2\bigskipamount]
  \large{}
  Questions? Comments? Bug reports? Mail to: \texttt{gildas@iram.fr}\\[2\bigskipamount]
  The \gildas{} team welcomes an acknowledgment in publications\\
  using \gildas{} software to reduce and/or analyze data.\\
  Please use the following reference in your publications:\\
  \texttt{http://www.iram.fr/IRAMFR/GILDAS}\\[2\bigskipamount]
\end{center}

\begin{description}
\item[Documentation] \mbox{}\\
  \credit{J.~Pety$^{1,2}$}{N.~Rodriguez--Fernandez$^{1}$,
    S.~Guilloteau$^{3}$}{R.~Lucas, K.~Bouyoucef}
\item[Software] \mbox{}\\
  \credit{J.~Pety$^{1,2}$}{S.~Guilloteau$^{3}$, F.~Gueth$^{1}$,
    N.~Rodriguez--Fernandez$^{1}$}{R.~Lucas, K.~Bouyoucef}
\end{description}
1. IRAM\\
2. Observatoire de Paris\\
3. Observatoire de Bordeaux

\begin{rawhtml}
  Note: this is the on-line version of the MAPPING Manual.
  A <A HREF="../../pdf/map.pdf"> PDF version</A>
  is also available.
\end{rawhtml}

\bigskip{} %

Related information is available in:
\begin{latexonly}
  \begin{itemize}
  \item{IRAM Plateau de Bure Interferometer: Introduction}
  \item{IRAM Plateau de Bure Interferometer: OBS Users Guide}
  \item{IRAM Plateau de Bure Interferometer: Atmospheric Calibration}
  \item{IRAM Plateau de Bure Interferometer: Calibration Cookbook}
  \item{CLIC: Continuum and Line Interferometric Calibration}
  \item{MIS:  Millimeter Interferometry Simulation Tools}
  \item{GREG: Graphical Possibilities}
  \item{SIC:  Command Line Interpretor}
  \end{itemize}
\end{latexonly}
%
\begin{rawhtml}
  <UL>
  <LI> IRAM Plateau de Bure Interferometer: <A HREF="../noema-intro-html/noema-intro.html">
  Introduction</A>
  <LI> IRAM Plateau de Bure Interferometer: <A HREF="../obs-html/obs.html"> 
  OBS Users Guide</A>
  <LI> IRAM Plateau de Bure Interferometer: <A HREF="../pdbi-cookbook-html/pdbi-cookbook.html"> 
  Calibration CookBook</A>
  <LI> <A HREF="../clic-html/clic.html"> CLIC:</A>  
  Continuum and Line Interferometric Calibration 
  <LI> <A HREF="../mis-html/mis.html"> MIS:</A>
  Tools for Millimeter Interferometry Simulation
  <LI> <A HREF="../greg-html/greg.html"> GREG: Graphical Possibilities</A>
  <LI> <A HREF="../sic-html/sic.html">   SIC:  Command Line Interpretor</A>
  </UL>
\end{rawhtml}

\newpage
\tableofcontents{} %

\mainmatter{} %

\chapter{Warning}

Rewriting this documentation from scratch made us think about the
\mapping{} user interface. Since then, we have thus rewritten this
interface mostly from scratch. This implies that this documentation is
already lagging. We will work to update it. In the meantime, we start to
distribute this version because we think it is anyway better (even though
far from perfect) than the old one.

\chapter{Basic concepts}

\section{Overview of the data reduction and analysis}

Once the data has been acquired by an interferometer such as the IRAM
Plateau de Bure Interferometer (\PdBI{}) data, two different approaches may
be used for its reduction and analysis:
\begin{itemize}
\item The first possibility is to clearly separate 1) the calibration, 2)
  the imaging and deconvolution and 3) the analysis.
\item The second possibility is to merge in a single step calibration and
  imaging. This possibility is known as self-calibration.
\end{itemize}
\gildas{} mainly implements the first approach, as the program and the data
format used for each step is different. The calibration of \PdBI{} data is
done inside \clic{} on the \PdBI{} raw data format and the outcome is a
\uv{} table, which contains only calibrated visibilities of the
astronomical source.  The imaging and deconvolution is done inside
\mapping{} on the calibrated \uv{} table and deliver mainly an \lmv{}
spectra cube (2 axes of coordinates and 1 axis of velocity/frequency).
Finally, the \greg{} program implements several tools to visualize and
analyze an \lmv{} spectra cube as those functionalities are not specific to
an interferometer (\eg\ the user can use them as well on 30m spectra cube).
It happens that those visualization and analysis functionalities are also
shipped inside the \mapping{} program so that the user do not have to
change program between the deconvolution and analysis.

The choice of clearly separating calibration and imaging+deconvolution was
taken at start of the \PdBI{}, when the limiting number of antenna forbid
the use of self-calibration. This choice turned out to be useful for
several reasons: 1) It simplified the structure of each program by keeping
at the minimum the complexity of the data format required at each step. 2)
It ensured clear responsibility between developers. 3) It enabled
well-defined break points in data reduction and analysis in steps which are
more and more generic: While many points of the calibration algorithms
inside \clic{} are specific to \PdBI{} data (in particular its range of
Signal-to-Noise ratio), the algorithms of imaging+deconvolution can be used
in many different contexts and the visualization and analysis of spectra
cubes is mainly independent of the instrument that delivered the data. This
last point implies that users can import data (mainly through FITS format)
in \mapping{} for imaging and deconvolution and in \greg{} for
visualization and analysis. But the reverse is also true: While calibration
of \PdBI{} data should be done inside \clic{}, imaging+deconvolution and
visualization+analysis can be done in other softwares (\eg\ \miriad{},
\aips{}, \aipspp{} newly called \casa{} for the imaging and deconvolution
and \karma{} for the visualization and analysis).

With the improvements of \PdBI{} (increase of the number of antennas and
better receiver sensitivities) and with the advent of a new generation of
interferometer (\ALMA{}), an additional step of self-calibration may
improve the consistency of the final results by imposing additional
consistent constraints on the calibration. We are now exploring this
possibility in \mapping{}.

\section{The structure of the \mapping{} program}

\subsection{Structure and recommendations}

The \mapping{} program supports
\begin{itemize}
\item The manipulation (\eg\ resampling), visualization and flagging of
  \uv{} tables;
\item The imaging of \uv{} tables in dirty maps and beams;
\item The deconvolution of dirty maps;
\item The inclusion of short-spacings from 30m data into \PdBI{} data;
\item The visualization and analysis of spectra cubes, mainly by
  importation of the \greg{} capabilities;
\item A simulator of ALMA continuum observations.
\end{itemize}
Those steps can be done in the following different ways
\begin{itemize}
\item A collection of tasks activated via the \com{RUN} command;
\item A collection of \sic{} procedures (the \com{GO} and \com{INPUT}
  families) which either wraps the calling of tasks to ease the
  specifications of their input parameters (\eg\ \comm{GO}{CLEAN}) or code
  a complex series of native \mapping{} commands to achieve a well-defined
  goal (\eg\ \comm{GO}{UVALL});
\item A collection of commands, either dedicated to image and deconvolution
  (the \lang{clean} language) or implementing basic functionalities (the
  \lang{sic} and \lang{greg} families of languages);
\item A collection of widgets grouped in the \mapping{} main menu to
  interface most of the above possibilities.
\end{itemize}
We recommend the following general strategy to select the ``right'' way of
doing one operation
\begin{itemize}
\item If a command of the \clean{} language implements this operation,
  always use it even though this possibility may also be implemented as a
  procedure and/or a task (\eg\ \verb|CLEAN\UV_MAP|, \comm{GO}{UV\_MAP} and
  \comm{RUN}{UV\_MAP}). This is because our minimum goal is the maintenance
  of the \clean{} language, not of the tasks (as long as the tasks do not
  share the same code as the \clean{} language).
\item If a \com{GO} procedure or a widget and a task implement this
  operation, always prefer the use of the procedure or the widget over the
  use of the task as procedure or the widget were designed to ease the
  interaction with the task, \ie\ they wrap the call of the task anyhow.
\item If this operation is coded only as a task or a procedure, avoid
  reinvent the wheel, just use it.
\end{itemize}
There may be exceptions to those recommendations: Always follow the
detailed indications of the manual.

\subsection{A bit of history}

Implementation of imaging and deconvolution algorithms inside \gildas{}
started in the early nighties. The first implementation was made as a
collection of independent programs, called tasks in the \gildas{}
environment, and activated through the \com{RUN} command in the \graphic{}
program. The main advantage was the ease of programing, the main drawback
was the lack of user-friendliness. To tackle this drawback, two different
approaches were used.
\begin{itemize}
\item First, the calling of tasks were hidden through the call to \sic{}
  procedures (the \com{GO} and \com{INPUT} families of scripts) whose
  behaviors was modified by global variables. The activation of the tasks
  and the development of the \sic{} procedures happened in a preexisting
  program, called \graphic{} which also contained the tools to visualize
  and analyze the spectra cubes.
\item Second, a single, big program, called \mapping{}, was developed with
  flexibility in mind, \eg\ the possibility to interactively define
  supports where to search for clean components. The support for
  deconvolution of mosaics was built only in \mapping{}. The same procedure
  names were used in \mapping{} and \graphic{} to obtain the same
  look-and-feel.
\end{itemize}
Up to 2003, there thus were two \gildas{} program, \ie\ \mapping{} and
\graphic{}, which offered slightly different services with procedures
sharing the same names. The status of the \graphic{} program was difficult
to understand as it shared similarities with the \greg{} program (which
defines all the drawing commands of \gildas{}) and with the \mapping{}
program. We thus decided during the 2003 change of \gildas{} architecture
to transfer the visualization and analysis capacities of \graphic{} in
\greg{} and the imaging and deconvolution capacities of \graphic{} in
\mapping{}.  The \graphic{} program was deprecated and we made the \greg{}
and \mapping{} program able to understand the \texttt{graphic} extension of
procedure files for backward compatibility. The major drawback of this
decision is the fact that we currently have in the same program (\ie\ 
\mapping{}) both tasks, procedures and commands to do similar but slightly
different things.  Not much happened following this step due to manpower
shortage in the \gildas{} team. Our goal in the coming years is to clean
this situation by ensuring that both tasks and commands use the same
FORTRAN code.  Our first main step is to update the documentation.

\section{Cookbook for the impatient ones}

This section presents typical deconvolution sessions on a real example
available in the \gildas{} distribution.

\subsection{Imaging and deconvolution pipeline}

\begin{verbatim}
       1 sic copy gag_demo:demo.uvt 1mm.uvt
       2 let name 1mm
       3 go uvcov 
       4 go uvall
       5 input uvall
       6 let xtype weight
       7 go uvall
       8 go image
       9 let type beam
      10 go bit
      11 let type lmv
      12 go bit
      13 let type lmv-res
      14 go bit
      15 let type lmv-clean
      16 go bit
      17 exit
\end{verbatim}
Comments:
\begin{description}
\item[Step 1] Copy a demonstration \uv{} table in the \gildas{}
  distribution in the current directory.
\item[Steps 2-7] Visualization of different aspects of \uv{} data directly
  from the file. Step 3 shows the \uv{} coverage. Step 4 displays the
  scatter plots of the amplitude vs spatial frequency of the \uv{}
  visibilities (default of the \comm{GO}{UVALL} procedure). Step 5 displays
  the value of the parameters which modify the behavior of the
  \comm{GO}{UVALL} procedure. Steps 6 and 7 display the scatter plots of
  the amplitude vs weight of the \uv{} visibilities.
\item[Step 8] Imaging and deconvolution pipeline with visualization of the
  deconvolved image using default parameters. The result is clearly not
  optimal in this case (see next section).  All the results are directly
  written as files on disk with the following file name conventions: dirty
  beam: \texttt{1mm.beam}, dirty image: \texttt{1mm.lmv}, clean image:
  \texttt{1mm.lmv-clean}, clean residuals: \texttt{1mm.lmv-res}.
\item[Step 9-14] Successive visualization of the dirty beam (steps 9 and
  10), dirty image (steps 11 and 12), clean residuals (steps 13 and 14) and
  clean image (steps 15 and 16).
\end{description}

\subsection{Finely tuned imaging and deconvolution}

\begin{verbatim}
       1 lut rainbow3  
       2 read uv 1mm
       3 uv_show
       4 uv_stat weight
       5 input uv_map
       6 let weight_mode UN
       7 let uv_cell 7.5 1
       8 uv_map
       9 show beam
      10 show dirty
      11 input clean
      12 let niter 1000
      13 hogbom /flux 0 0.6
      14 show residual
      15 let niter 2000
      16 hogbom /flux 0 0.6
      17 show residual
      18 let niter 4000
      19 hogbom /flux 0 0.6
      20 show residual
      21 show clean
      22 support
      23 hogbom /flux 0 0.6
      24 show residual
      25 show clean
      26 write beam 1mm
      27 write dirty 1mm
      28 write clean 1mm
      29 write residual 1mm
      30 write cct 1mm
      31 exit
\end{verbatim}
Comments:
\begin{description}
\item[Step 1] Select a color lookup table which nicely displays the
  features of the studied source.
\item[Step 2] Read \uv{} data from the \texttt{1mm.uvt} file to an internal
  \mapping{} buffer.
\item[Step 3] Displays the scatter plot of the amplitude vs spatial
  frequency of the \uv{} visibilities. This commands is similar to the
  \comm{GO}{UVALL} command (see previous section), except that it works
  only on the data previously loaded in the internal buffer.
\item[Step 4] Predicts the synthesized beam, expected noise level, and
  recommended pixel size for different values of the robust weighting
  threshold. This helps the user to select the threshold used in the
  imaging steps (2nd parameter of the \texttt{uv\_cell} variable).
\item[Steps 5-10] Compute a tailored dirty beam and dirty image. Step 5
  displays the \sic{} variables that customizes the behavior of the
  \com{UV\_MAP} command. Step 6 and 7 selects robust weighting (instead of
  the default natural weighting) and the associated threshold. Step 8
  actually computes the results which are stored in internal buffers and
  visualized in steps 9 and 10.
\item[Steps 11-14] First deconvolution on internal buffers. Resulting clean
  residuals, clean image and clean component tables are also stored in
  internal buffers. Step 11 displays the \sic{} variables that customizes
  the behavior of all the clean deconvolution algorithms. Steps 12 select
  the stopping criterion by enabling a maximum of 1000 clean components.
  Step 13 launches the deconvolution using the simplest \clean{} algorithm
  with simultaneous plot of the cumulative flux as a function of the number
  of found clean components. Step 14 displays the residuals, \ie\ remaining
  undeconvolved signal.
\item[Steps 15-24] Successive tries of the deconvolution to ensure deep
  enough cleaning, just by changing the stopping criterion (here the total
  number of clean components).
\item[Step 25] Displays the resulting clean image.
\item[Steps 26-30] Write the results (dirty beam, dirty image, clean image,
  clean residuals and clean component table) on disk files for use in
  future sessions.
\end{description}

\subsection{Noise estimation and plotting}

\begin{verbatim}
       1 let name 1mm
       2 let type lmv-clean
       3 go cct
       4 go noise
       5 let spacing '3*noise'
       6 go bit
       7 hardcopy 1mm-clean
       8 exit
\end{verbatim}
Comments:
\begin{description}
\item[Steps 1-3] Visualize the cumulative flux as a function of the number
  of found clean components to get an idea of the cleaning convergence.
\item[Step 4] Computes an experimental noise value which takes into account
  possible remaining side lobes after deconvolution.
\item[Step 5] Sets the spacing between contour levels to 3 times the
  experimental noise value (the \texttt{noise} \sic{} variable was defined
  by the \comm{GO}{NOISE} procedure).
\item[Step 6] Visualizes the clean image with the right values for the
  contour levels.
\item[Step 7] Makes a color Post-Script file, named \texttt{1mm-clean.eps},
  of the plot.
\end{description}

\chapter{Interacting with \uv{} tables}

\section{Structure}

A \uv{} table is a file which usually contains calibrated visibilities
ready for imaging and deconvolution. It thus is the main input of the
\mapping{} program. The \uv{} table format is a particular example of the
Gildas Data Format (GDF\footnote{A binary format made of a header plus an
  array whose dimension is between 1 and 4}). It contains a header plus a
table, \ie\ an array of dimension two composed of lines and columns.

\subsection{\uv{} table}

In a \uv{} table, each line describe one and only one visibility. The
number of lines of the table is thus the number of visibilities described
in the table. Each column of the table stores a particular property of the
visibilities, namely:
\begin{description}
\item[Line 1] U in meters;
\item[Line 2] V in meters;
\item[Line 3] Scan number;
\item[Line 4] Observation date (integer \class{}/\clic{} Day
  Number\footnote{The \class{}/\clic{} is a "radio Julian date" (or "Jansky
    Julian date"), which starts as $-2^{15}$ on the date of the first radio
    observation by Karl Jansky. It is thus the Modified Julian date minus
    60549.  That choice was made to maximize the time interval over which
    radio astronomical data could be usefully stored in an
    \texttt{integer*2}, back when 2 bytes of header space per spectrum were
    a significant consideration.  This date has little meaning outside the
    rather sparse community of souls gathered around the \class{} and
    \clic{} programs, however...});
\item[Line 5] Time in seconds since 0:00 UT of above date;
\item[Line 6] Number of the first antenna used to measure the visibility;
\item[Line 7] Number of the second antenna used to measure the visibility;
\item[Line 8] Real part for the first frequency channel;
\item[Line 9] Imaginary part for the first frequency channel;
\item[Line 10] Weight for the first frequency channel;
\item[Lines 11-13] Same as column 8-10 but for the second frequency
  channel;
\item[...]
\end{description}
If a \uv{} table describes \texttt{nvis} visibility spectra composed of
\texttt{nchan} frequency channels, the size of the table will thus be:
\texttt{nvis} lines of \texttt{7+3*nchan} columns.

\subsection{\uv{} header}

A \uv{} table header contains all the informations of a GDF header but some
of these informations have a special meaning in this context. The
\com{HEADER} is the standard way inside \gildas{} to display in a human
readable way the header of GDF file. For instance, \texttt{MAPPING> header
  12cs21.uvt} would display
\begin{verbatim}
       1  W-GDF_RHSEC,  Absent section NOISE
       2  File : 12cs21-1.uvt                                                  REAL*4
       3  Size        Reference Pixel           Value                  Increment
       4     154   25.50000000000000       97980.02890200325     -6.5365856842222472E-02
       5    1320   0.000000000000000       0.000000000000000       1.000000000000000
       6       1   0.000000000000000       0.000000000000000       0.000000000000000
       7       1   0.000000000000000       0.000000000000000       0.000000000000000
       8  Blanking value and tolerance      1.23455997E+34   0.0000000
       9  Source name         HORSEHEAD
      10  Map unit            Jy
      11  Axis type           UV-RAW       RANDOM       UNKNOWN      UNKNOWN
      12  Coordinate system   EQUATORIAL
      13  Right Ascension     05:40:53.903        Declination        -02:28:22.00
      14  Lii        206.9592680349889            Bii      -16.80061668685155
      15  Epoch              2000.0000
      16  Projection type     AZIMUTHAL           Angle     0.000000000000000
      17  Axis 0     A0       05:40:54.270        Axis 0     D0      -02:28:00.00
      18  Minimum            0.0000000      at     0     0     0     0
      19  Maximum            0.0000000      at     0     0     0     0
      20  Axis 1 Line Name    12CS(2-1)           Rest Frequency   97980.95299999999
      21  Resolution in Velocity   0.20000000     in Frequency   -6.5365856842222472E-02
      22  Offset in Velocity        10.500000     Image Frequency  0.000000000000000
      23  Noise
      24  Beam                     2.494E-04   0.00       0.00
\end{verbatim}
Comments:
\begin{description}
\item[Line 2] Indicates the filename associated to the currently displayed
  header.
\item[Lines 3-7] Display the dimensions of the associated array. Here it is
  a rank 2 array of dimension 1320 columns times 154 lines, \ie\ 1320
  visibility spectra of 49 frequency channels (see previous section).  Line
  4 describes the frequency axis of the visibility spectra stored in the
  \uv{} table. Be careful that this is a convention, \ie\ it must be
  decoded using the particular form of the table. In our case, each spectra
  has 49 frequency channels of width -65.36~kHz, the frequency of the
  reference pixel 25.50 corresponding to 97980.02890200325~MHz. This last
  frequency is the frequency delivered by the correlator, \ie\ seen by the
  observatory. In particular, this is the frequency that must be used to
  compute the primary beam of the interferometer.
\item[Line 10] Indicates the unit of the real and imaginary parts of the
  visibilities. *** Weights unit? JP ***
\item[Line 11] Indicates that this is \uv{} table (\texttt{UV-RAW} and
  \texttt{RANDOM}).
\item[Lines 12-15] Describe the coordinate system.
\item[Lines 16-17] Describe the projection system. In the \uv{} table
  format, \texttt{A0} and \texttt{D0} indicate the phase center while
  \texttt{Right Ascension} and \texttt{Declination} indicate where the
  antenna pointed when acquiring the signal. These information are in
  general identical for single field imaging and different for mosaicing.
\item[Lines 18-19] Unused for \uv{} tables.
\item[Lines 20-22] Describe additional information about the frequency axis
  of the visibility spectra. In particular, the rest frequency (here
  97980.953 MHz) corresponding to a velocity of 10.5~km/s in the velocity
  frame (in general LSR).
\item[Line 23] Unused for \uv{} tables.
\item[Line 24] Indicates the primary beam size of the interferometer in
  radian (This is an indirect way to pass the size of the interferometer
  antennas).
\end{description}

\section{Interacting with \uv{} table}

\subsection{Basics}
\label{sec:uv:inter:basics}

A \uv{} table being a particular type of the GDF format, all the \sic{} and
\greg{} commands can be used on \uv{} tables. Here is a typical example:
\begin{verbatim}
       1 transpose 12cs21.uvt 12cs21.tuv 21
       2 column x 1 y 2 /table 12cs21.tuv
       3 limits
       4 box
       5 points
       6 define image tuv 12cs21.tuv read
       7 limits /var tuv[1] tuv[2]
       8 box
       9 points uv[1] uv[2]
      10 define double mjd /like tuv[1]
      11 let mjd tuv[4]+tuv[5]/24.
      12 delete /var tuv
      13 define image tuv 12cs21.tuv write
      14 for ichan 1 to (tuv%dim[2]-7)/3
      15    let tuv['7+3*ichan'] -tuv['7+3*ichan'] /where tuv['5+3*ichan',].ge.100.0
      16 next ichan
      17 delete /var tuv
\end{verbatim}
Comments:
\begin{description}
\item[Step 1] Transposes columns and lines of the \uv{} table. Indeed,
  \clic{} naturally produces the \uv{} tables in visibility order, which is
  not well suited for display where it is more useful to have all
  information about a visibility in a line than in a column. By convention,
  the extension of transposed \uv{} tables is \texttt{tuv}.
\item[Steps 2-5] Read and plot the $u$ and $v$ coordinate to give an idea
  of the \uv{} coverage of the data inside the table.
\item[Steps 6-12] Steps 6 to 9 gives the same result as steps 2 to 5 except
  than here all the table is red and stored in the sic \texttt{tuv}
  variable. This enables computation of complex quantities from several
  table column, \eg\ the computation of a continuous variable of time (mjd)
  in steps 10 and 11.
\item[Steps 13-17] Change the sign of the weight columns for all
  visibilities whose real amplitude is greater or equal to 100.0. Changing
  the sign of the weight is a reversible way to flag out a visibility.
  Indeed, it is always possible to change again the sign. This operation is
  done in place, \ie\ the input file is overwritten in step 17 as announced
  by the \texttt{write} option of command \texttt{define} in step 13.
\end{description}

\subsection{Advanced}

Finally, it is sometimes useful to order the \uv{} table either in
ascending, negative V values or in ascending time-baseline order. This can
be done through the \texttt{UV\_SORT} task.

%UV_CLIP

%UV_SHIFT

%UV_CIRCLE

%UV_SUBTRACT

%*** Help of this task must be updated. What about \texttt{UV\_SORT} command?
%This command does not work twice in a raw... JP ***

\section{Visualization (\comm{GO}{UVALL} and \comm{GO}{UVCOV})}

Although images are a wonderful way to display results, problems may be
more obvious in scatter plots of visibilities. For instance, large strips
in the dirty image often originates from a single outlier visibility.
\comm{GO}{UVALL} is a procedure to explore the content of a \uv{} table
through visualization of scatter plots. This procedure is controlled by
several input parameters, in particular the following global variables
\begin{description}
\item[\texttt{NAME}] The filename without extension of the input \uv{}
  table;
\item[\texttt{XTYPE} and \texttt{YTYPE}] The types of data to be plotted
  along the X and Y axes. These two variables can take the following values
  \begin{description}
  \item[\texttt{u} or \texttt{v}] Fourier coordinates [m];
  \item[\texttt{radius}] \uv{} distance (\texttt{$\sqrt{U^2+V^2}$}) [m];
  \item[\texttt{angle}] \uv{} position angle (\texttt{atan2(V,U)}) [deg];
  \item[\texttt{time}] UT time of observation [hrs];
  \item[\texttt{date}] Date of observation [days];
  \item[\texttt{scan}] Scan number;
  \item[\texttt{number}] Visibility number in \uv{} table;
  \item[\texttt{amp}] Amplitude of visibility [Jy];
  \item[\texttt{phase}] Phase of visibility [deg];
  \item[\texttt{real}] Real part of visibility [Jy];
  \item[\texttt{image}] Imaginary part of visibility [Jy];
  \item[\texttt{weight}] Weights of visibility [*** ? JP ***].
  \end{description}
  The default is to plot the amplitude vs the radius of the visibilities.
\item[\texttt{FIRST} and \texttt{LAST},] \ie\ the first and last channel to
  plot. By default, all channels are plotted.
\end{description}
Other input parameters are available. Please type \texttt{input uvall} to
obtain the most recent available help. For instance, to obtain the scatter
plots of amplitude vs weight of the visibility (which should look like an
hyperbole), you would type:
\begin{verbatim}
       1 let name 12cs21
       2 let xtype weight
       3 let ytype radius
       4 go uvall
\end{verbatim}
The plot of the \uv{} coverage of the data is such an important subset of
the \comm{GO}{UVALL} possibility that we created a dedicated procedure for
it, namely \comm{GO}{UVCOV}.

\section{Flagging (\com{UV\_FLAG}, \comm{RUN}{UV\_MFLAG}, \comm{RUN}{UV\_CLIP})}

The experience shows that flagging out \PdBI{} data inside \mapping{}
rarely improve the results. This is the consequence of several factors: 1)
The on-line \PdBI{} system quite efficiently catch possible observations
problems (\eg\ phase unlock); 2) A particular care has been taken in the
computation of the relative weights so that data taken in poor observing
conditions will almost not affect the result. Finally, it is extremely
difficult to flag data based on the data itself and a \uv{} table is an
extremely compact data format which has lost most of the information needed
to make intelligent flagging. This is why we recommend the use of tools
like the ``quality assessment tool'' in \clic{} which selects good
on-source data based on observing conditions (\eg\ weather, tracking, ...).
This said, \mapping{} offers several tools to enable data flagging in the
few cases where it can be useful like the presence of a single clearly
outlier visibility.

\begin{description}
\item[\com{UV\_FLAG} command] Display \uv{} data (controled by similar
  variables than \comm{GO}{UVALL}) and calls the cursor to interactively
  select a region where \uv{} data will be flagged. The data are flagged by
  changing the sign of the weight. Subsequent mapping with \com{UV\_MAP}
  will ignore flagged data. The flagged UV table can be saved on a file
  with command \comm{WRITE}{UV} File. The \texttt{/RESET} option can be
  used to unflag the data (all the flagged data, not interactive).
\item[\com{UV\_FLAG} task] Flag or unflag a specified time range in a \uv{}
  data set, for one or all baselines and a specified channel range.  {\it
    HOW CAN WE SEE EASILY THE TIME ?}
\item[\com{UV\_CLIP} task] Clip \uv{} data with amplitudes higher than a
  given threshold.  For spectroscopic data, all channels are flagged if any
  channel between the first and last considered has an amplitude greater
  than the trheshold. Clipped channels are set to zero amplitude and zero
  weight.  {\it \bf It doesn't seem to work. First due to old data format,
    but after using uvt\_convert it does not work neither }
\item[\com{UV\_MFLAG} task] Compare the PdBI uv table with an uv table
  calculated from a model source and flag the data if the REAL part of the
  visibility differs from the model in more that a given tolerance.  Data
  are flagged setting weights to 0. {\it NOT TESTED}
\end{description}

\section{Fitting (\comm{GO}{UVFIT} and \comm{GO}{PLOTFIT})}

\subsection{General considerations}

The first output of a millimeter interferometer is a set of calibrated
visibilities in the \uv{} plane. Scientific analysis of this kind of data
is possible in two different ways
\begin{description}
\item[Analysis in the image plane], \ie\ analysis on images which are made
  from the \uv{} visibilities. This is the most common kind of analysis but
  it implies (complex) mathematical transforms (\ie\ imaging and
  deconvolution) which may bring some artifacts in the results. This is the
  subject of the next chapter.
\item[Analysis in the \uv{} plane], \ie\ fitting of a source model through
  the \uv{} visibilities. When possible, it is the best analysis mode
  because it avoids the imaging and deconvolution steps. For instance, this
  enables the precise determination of the properties of proto-planetary
  disks (geometry, Keplerian rotation, etc...). However, the fit process
  implies the use of an underlying model of the source. This limits the use
  of this analysis mode to the ``simplest'' objects. It must also be used
  with much critical sense as the use of a wrong fitting model may largely
  bias the result: \eg\ trying to fit an circular Gaussian through an
  elliptical one will give a biased full width at half maximum. In
  practice, a really important use of this analysis mode is the fit of
  simple models (point, Gaussian, etc...) through unresolved (or slightly
  resolved) sources, in particular at low signal-to-noise
  ratio\footnote{Indeed, low signal-to-noise ratio is a condition where
    imaging and deconvolution steps are very delicate.}. \mapping{} offers
  tools dedicated to this special goal.
\end{description}

\subsection{Implementation}

The \mapping{} fitting capabilities are available through the
\comm{GO}{UVFIT} and \comm{GO}{PLOTFIT} procedures and/or the associated
widgets (inside the \texttt{UV interferometric operations} widget of the
\mapping{} menu). These procedures allow you to fit models directly through
the visibilities of a \uv{} table whose filename (without extension) is
stored into \texttt{NAME} sic variable. The models are either simple
functions or linear combinations of simple functions. The residual \uv{}
visibilities will be written in a \uv{} table named
\texttt{'NAME'"-res.uvt"}. The results (\eg\ values of the fitted
parameters) will be saved in an output binary file (in detail, a
\texttt{GDF} table), named \texttt{'NAME'".uvfit"}. The velocity/frequency
channels to be fitted are selected through the \texttt{FIRST} and
\texttt{LAST} sic variables.

All other control parameters of the fit and of the plot of the fitted
parameters are stored in the \texttt{UVFIT} sic structure
\begin{description}
\item[Fit parameters] are
  \begin{description}
  \item[\texttt{UVFIT\%RANGE}] The range (in meters) of spatial scales to
    be used in the fitting. \texttt{"0 1700"} is the correct default as of
    today (2023) for \NOEMA{}.
  \item[\texttt{UVFIT\%NF}] Number of simple fitted functions. Both the
    task and the procedure enable the fit of the linear combinations of up
    to four simple functions while the widget gives support only for the
    combination of two simple functions. Indeed, the larger the number of
    simultaneously fitted function , the more difficult the convergence...
    Each of the following parameters is suffixed with the number of the
    fitted function it contributes to describe (\eg\ 01, 02, 03, 04).
  \item[\texttt{UVFIT\%FUNCT01}] Currently supported functions are\\
    \begin{tabular}{lll}
      \texttt{POINT}    & Point source               & X and Y offset, flux \\                                 
      \texttt{E\_GAUSS} & Elliptical Gaussian        & X and Y offset, flux, major and minor FWHM, pos. ang. \\ 
      \texttt{C\_GAUSS} & Circular Gaussian          & X and Y offset, flux, FWHM \\                            
      \texttt{C\_DISK}  & Circular disk              & X and Y offset, flux, diameter \\                             
      \texttt{E\_DISK}  & Elliptical (inclined) disk & X and Y offset, flux, axes (major and minor), pos. ang. \\      
      \texttt{RING}     & Annulus                    & X and Y offset, flux, inner and outer diameter  \\           
      \texttt{U\_RING}  & *** ? JP ***               & X and Y offset, flux, *** ? JP *** \\                                  
      \texttt{EXPO}     & Exponential brightness     & X and Y offset, flux, FWHM axis \\                            
      \texttt{POWER-2}  & $B = 1/r^2$                & X and Y offset, flux, FWHM axis \\                            
      \texttt{POWER-3}  & $B = 1/r^3$                & X and Y offset, flux, FWHM axis \\                            
    \end{tabular}
    The number and description of the fitted parameters depends on the kind
    of fitted functions. As can be seen, at least 3 parameters are always
    fitted and the first 3 parameters are common to all fitted functions.
    Fluxes are expressed in Jansky and sizes in arcseconds.
  \item[\texttt{UVFIT\%PARAM01}] Guesses of input parameters in the order
    defined in the above table. Six parameters must always be given. You
    can put whatever value for the parameters that will not be used in the
    fit. \emph{Important warning: The guess of spatial length (\eg\ major,
      minor) must be non-zero valued, otherwise it will stay zero during
      the fit...}
  \item[\texttt{UVFIT\%START01}] Number of time the fit will be started
    with slightly different input parameters in agreement with the value of
    \texttt{UVFIT\%RANGE01}. The default (\ie\ 0) means that the fit will
    be started only once with the values of \texttt{UVFIT\%PARAM01} as
    initial guess. The value of -1 is an important particular case. Indeed
    -1 implies that the associated parameters will \emph{not} be fitted. It
    will instead keep the initial guess value.
  \item[\texttt{UVFIT\%RANGE01}] Not fully clear *** ? JP ***
  \item[\texttt{UVFIT\%SUBSF01}] Logical variable indicating whether the
    associted fitted function will be subtracted from the input \uv{} table
    in the residual \uv{} table.
  \end{description}
\item[Plot parameters] are
  \begin{description}
  \item[\texttt{UVFIT\%NP}] Number of fitted functions for which the values
    of the fitted parameters will be plotted. Each fitted function will be
    associated one color.
  \item[\texttt{UVFIT\%ORDER}] Order in which the fitted functions will
    have their parameters plotted. For instance, if you want to plot only
    the parameters of the second fitted function, you would set
    \texttt{UVFIT\%NP} to 1 and \texttt{UVFIT\%ORDER} to \texttt{"2 1"}.
  \item[\texttt{UVFIT\%NX} and \texttt{UVFIT\%XTYPE}] Number and type of
    the fitted parameters used to define the X axes of the plots. Up to 6
    parameters can be plotted in the same plot. The \texttt{UVFIT\%XTYPE}
    must be a string formatted like \texttt{"type min max"}.  Possible type
    are \texttt{CHANNEL, VELO, FREQ, RMS, RA, DEC, FLUX, WIDTH, MAJOR,
      MINOR, and ANGLE}. A \texttt{[*]} instead of min and/or max implies
    the use of the default minimum and maximum values of the plotted
    parameter.
  \item[\texttt{UVFIT\%NY} and \texttt{UVFIT\%YTYPE}] Idem for the Y axes.
  \end{description}
\end{description}
A known bugs is that when you change the number of simultaneously fitted
functions, you need to manually remove the \texttt{uvfit} file to avoid
trouble. % *** This should be corrected asap! JP ***

The procedures are in fact wrap-up around the \com{UV\_FIT} task. It uses
the public domain \textsc{slatec} library which is shipped by default with
\gildas{}.

The results are stored in a GDF table which can read with the \com{COLUMN}
command. The table is organized as a $M \times N$ matrix. $M$ is the number
of channels in the input table.  The organization along the other axis is
as follows \texttt{P1 P2 P3 Vel A1 A2 A3 Par1 Err1 Par2 Err2 ... A1 A2 A3
  Par1 Err1 ...} where
\begin{description}
\item[\texttt{P1}] RMS of the fitting process.
\item[\texttt{P2}] Number of simultaneously fitted functions.
\item[\texttt{P3}] Total number of fitted parameters.
\item[\texttt{Vel}] Velocity of the ith channel (i lies between 1 and M).
\item[\texttt{A1}] Number of the fitted function (1 for the first function,
  2 for the second function, ...).
\item[\texttt{A2}] Code of the function kind (POINT = 1, E\_GAUSS = 2,
  ...).
\item[\texttt{A3}] Number of fitted parameters in the current function.
\item[\texttt{Par1}] Value of the first fitted parameters.
\item[\texttt{Err1}] Uncertainty on the value of the first fitted
  parameters.
\end{description}
Hence, $N=19$ when fitting a single function (4 generic columns + 3 columns
associated to the fitted function + 6 times 2 columns per parameters) and
$N=34$ when fitting simultaneously two functions.  This data format as the
use of the task itself is not very convenient. We thus recommend to use the
procedures and/or the associated widgets.

\subsection{Practical advices}

\begin{itemize}
\item Always make an image first. This is mandatory if you have no idea of
  the structure of your source but this is also useful since the image will
  directly show you the calibration problems, which are in general much
  more difficult to detect directly in the visibilities.
\item Use any knowledge you can have on your source. For instance, fitting
  a disk function is probably the most appropriate for barely resolved
  planets and satellites.
\item If your source is barely resolved and you have no \emph{a priori}
  knowledge of the source structure, you should start with the simplest
  possible model (\eg\ \texttt{POINT}) and complexify the model only
  gradually (\eg\ \texttt{C\_GAUSS}, \texttt{E\_GAUSS}, etc...). Verify how
  the uncertainties on the fitted parameters evolves to decide which model
  is most appropriate.
\item Always be critical with the results. In particular, image and
  deconvolve the residual $uv$ table. You should obtain just noise if the
  fit succeeded.
\end{itemize}

\section{The widget \texttt{Operations on uv tables}}

Fig.~??? shows the widget interface which has been designed around the most
usual operations that a user will do on a \uv{} table. These includes:
flagging out of outlier visibilities, scatter plots of \uv{} table data,
translation and rotation of coordinates, fits of simple geometry in the
\uv{} plane with the visualization of the fitted parameters.

\chapter{Single-field imaging and deconvolution}

\section{Measurement equation and other definitions}

The measurement equation of an instrument is the relationship between the
sky intensity and the measured quantities. The measurement equation for a
millimeter interferometer is to a good approximation (after calibration)
\begin{equation}
  V(u,v) = \mbox{FT}\cbrace{B_\emr{primary}.I_\emr{source}}(u,v)+N
\end{equation}
where $\mbox{FT}\cbrace{F}(u,v)$ is the bi-dimensional Fourier transform of
the function $F$ taken at the spatial frequency $(u,v)$, $I_\emr{source}$
the sky intensity distribution, $B_\emr{primary}$ the primary beam of the
interferometer (\ie\ a Gaussian whose FWHM is the natural resolution of the
single-dish antenna composing the interferometer), $N$ some thermal noise
and $V(u,v)$ the calibrated visibility at the spatial frequency $(u,v)$.
This measurement equation implies different kinds of problems.
\begin{enumerate}
\item The presence of noise leads to sensitivity problems.
\item The multiplication of the sky intensity by the primary beam implies a
  distortion of the information about the intensity distribution of the
  source.
\item The presence of the Fourier transform implies that visibilities
  belongs to the Fourier space while most (radio)astronomers are used to
  work in the image space. A step of \emph{imaging} is thus required to go
  from the \uv{} plane to the image plane.
\item Finally, the main problem implied by this measurement equation is
  certainly the irregular, limited sampling of the \uv{} plane because it
  implies that the information about the source intensity distribution is
  incomplete.
\end{enumerate}
To show that deconvolution techniques are needed to overcome the incomplete
sampling of the \uv{} plane, we need additional definitions
\begin{itemize}
\item Let's call $V = \mbox{FT}\cbrace{B_\emr{primary}.I_\emr{source}}$ the
  continuous visibility function.
\item The sampling function $S$ is defined as
  \begin{itemize}
  \item $S(u,v) = 1/\sigma^2$ at $(u,v)$ spatial frequencies where
    visibilities are measured by the interferometer. $\sigma{}$ is the rms
    noise predicted from the system temperature, antenna efficiency,
    integration time and bandwidth. The sampling function thus contains
    information on the relative weights of each visibility.
  \item $S(u,v) = 0$ elsewhere.
  \end{itemize}
\item We finally call $B_\emr{dirty} = \mbox{FT}^{-1} \cbrace{S}$ the dirty
  beam.
\end{itemize}
If we forget about the noise, we can thus rewrite the measurement equation
as
\begin{equation}
  I_\emr{dirty} = \mbox{FT}^{-1} \cbrace{S.V}.
\end{equation}
Using the property \#1 of the Fourier transform (see Appendix), we obtain
\begin{equation}
  I_\emr{dirty} = B_\emr{dirty} \ast \cbrace{B_\emr{primary}.I_\emr{source}},
\end{equation}
where $\ast$ is the convolution symbol. Thus, the incompleteness of the
\uv{} sampling translate in the image plane as a convolution by the dirty
beam, implying the need of deconvolution. From the last equation, it is
easy to show that the dirty beam is point spread function of the
interferometer, \ie\ its response at a point source. Indeed, for a point
source at the phase center, $\cbrace{B_\emr{primary}.I_\emr{source}} =
I_\emr{point}$ at the phase center and 0 elsewhere and the convolution with
a point source is equal to the simple product: $I_\emr{dirty} =
B_\emr{dirty}.I_\emr{point} = B_\emr{dirty}$ for a point source of
intensity $I_\emr{point} = 1$~Jy.

\section{Imaging}

\subsection{Image size, pixel size, robust weighting and tapering}

The process known as {\it imaging} consists in computing the dirty image
and the dirty beam from the measured visibilities and the sampling
function. This is done through Fast Fourier Transform, which implies first
a stage of gridding of the visibilities on a regular grid in the \uv{}
plane.

\subsubsection{Link between image size and \uv{} cell size}

The gridding requires at least Nyquist sampling of the \uv{} plane to avoid
the artifact known as aliasing. For the signal, the Nyquist sampling in the
\uv{} plane is obtained with a size of the grid cells equal to half the
size of the antenna diameter (this is the smallest spatial frequency that
the interferometer can be sensitive to, \ie\ the natural resolution in the
\uv{} plane). In the image plane, this implies to make an image at least
twice as large as the primary beam size (see Fourier transform property \#2
in appendix). Unfortunately, the spatial frequencies of the noise are not
bounded: Noise aliasing can not be avoided, \ie\ the noise increases at the
edges of the produced image.

\subsubsection{Link between pixel size and largest \uv{} spatial frequency}

The largest sampled spatial frequency is directly linked to the synthesized
beam size (\ie\ the interferometer spatial resolution). The pixel size must
be at least 1/2 the synthesized beam size to ensure Nyquist sampling in the
image plane. However, Nyquist sampling is enough only when dealing with
linear process while deconvolution techniques are non-linear process.  We
thus recommend to pick a pixel size between 1/3 and 1/4 of the synthesized
beam to ease the deconvolution. Unless you have good reasons, you should
not choose too large an image size nor too small a pixel size at least
because it would considerably slow down any deconvolution algorithm.

\subsubsection{Weighting}

The use of the visibility weights $(1/\sigma^2)$ in the definition of the
sampling function is called natural weighting as it is natural to weight
each visibility by the inverse of noise variance. Natural weighting is also
the way to maximize the point source sensitivity in the final image.
However, the exact scaling of the sampling function is an additional degree
of freedom of the imaging process. In particular, the user may change this
scaling to give more or less weight to the large/short spatial frequencies.

We can thus introduce a weighting function $W(u,v)$ in the definitions of
$B_\emr{dirty}$ and $I_\emr{dirty}$
\begin{equation}
  B_\emr{dirty} = \mbox{FT}^{-1} \cbrace{W.S}
\end{equation}
and
\begin{equation}
  I_\emr{dirty} = \mbox{FT}^{-1} \cbrace{W.S.V}.
\end{equation}
There are two main categories of weighting functions
\begin{description}
\item[Robust weighting] In this case, $W$ is computed to enhance the
  contribution of the large spatial frequencies. This is done by first
  computing the natural weight in each cell of the \uv{} plane. Then $W$ is
  derived so that
  \begin{itemize}
  \item The product $W.S$ in a \uv{} cell is set to a constant if the
    natural weight is larger that a given threshold;
  \item $W = 1$ (\ie{} natural weighting) otherwise.
  \end{itemize}
  This decreases the weight of the well measured \uv{} cells (\ie{} very
  low noise cells) while it keeps natural weighting of the noisy cells.  It
  happens that the cells of the outer \uv{} plane (corresponding to the
  large interferometer configurations) are often noisier that the cells of
  the inner \uv{} plane (just because there are less cells in the inner
  \uv{} plane). Robust weighting thus increase the spatial resolution by
  emphasizing the large spatial frequencies at the cost of a worst
  sensitivity to point sources...
\item[Tapering] is the apodization of the \uv{} coverage by simple
  multiplication of a Gaussian
  \begin{equation}
    W = \exp\cbrace{-\frac{\paren{u^2+v^2}}{t^2}},
  \end{equation}
  where $t$ is the tapering distance. This multiplication in the \uv{}
  plane translates into a convolution by a Gaussian in the image plane,
  \ie\ a smoothing of the result. The only purpose of this is to increase
  the sensitivity to extended structure. Tapering should almost never be
  used as this somehow implies that you throw away large spatial
  frequencies measured by the interferometer... In other words, use compact
  configuration of the arrays and not tapering to increase sensitivity to
  extended structures in your source.
\end{description}
For more details on the whole imaging process the interested reader is
referred to \cite{guilloteau00}.

\subsection{Implementation (\comm{READ}{UV}, \com{UV\_MAP} and \com{UV\_STAT})}

In \mapping{}, gridding in the \uv{} plane and computation of the dirty
beam and image are coded in the \com{UV\_MAP} command. This commands works
on an internal buffer containing the \uv{} table read from a file through
the \comm{READ}{UV} command. The \com{UV\_MAP} behavior is controlled
through the following sic variables
\begin{description}
\item[Gridding kernel] \mbox{}
  \begin{description}
  \item[\texttt{CONVOLUTION}] Gridding in the \uv{} plane is done through
    convolution and this variable is the kind of convolution kernel.
    Default is 5, meaning spheroidal functions. Unless you are a real
    expert, you should never change the value of this variable: Spheroidal
    functions are the right answer.
  \end{description}
\item[Data cube setup] \mbox{}
  \begin{description}
  \item[\texttt{WCOL}] Number of the used weight column. The default is to
    compute only one dirty beam for the whole data cube. This default may
    be incorrect when adding data obtain at different rest frequencies.
    % *** we should implement the ONEBEAM variable! JP ***
  \item[\texttt{MCOL}] First and last velocity/frequency channels to map
    (default value is 0 meaning all the channels).
  \item[\texttt{MAP\_CELL}] Pixel size in arcsec. Default is 0, meaning
    between 1/3 and 1/4 of the synthesized beam.
  \item[\texttt{MAP\_SIZE}] Map size in pixel. Default is 0, meaning a
    power of two which gives about twice the size of the primary beam size.
    For efficiency of FFT, it is better to pick a power of two.
  \item[\texttt{MAP\_RA}] Right Ascension of the phase center. Default is
    an empty string, meaning do not change the right ascension.
  \item[\texttt{MAP\_DEC}] Declination of the phase center. Default is an
    empty string, meaning do not change the declination.
  \item[\texttt{MAP\_ANGLE}] Map position angle in degree. Default is 0,
    meaning do not rotate the map.
  \item[\texttt{UV\_SHIFT}] Logical which toggle the change of phase center
    and position angle. This may be used to align the map axes with a
    feature of interest of the source, by rotation of the \uv{}
    coordinates.
  \end{description}
\item[Weighting] \mbox{}
  \begin{description}
  \item[\texttt{WEIGHT\_MODE}] Kind of weighting. Possibilities are
    \texttt{NATURAL} or \texttt{UN} (which stands for \texttt{ROBUST}...).
    Default is \texttt{NATURAL} weighting to maximize the point source
    sensitivity.
  \item[\texttt{UV\_CELL}] Size of the \uv{} plane cell and threshold of
    the robust weighting. Default are 7.5~m (half the diameter of the
    \PdBI{} antenna) and 1.
  \end{description}
\item[Tapering] \mbox{}
  \begin{description}
  \item[\texttt{UV\_TAPER}] Properties of the Gaussian used to apodize the
    weights of the \uv{} visibilities (minor and major axes in meters and
    position angle in degree). Default is 0, meaning no tapering.
  \item[\texttt{TAPER\_EXPO}] *** ? JP *** Default is 0, meaning the use of
    a Gaussian as tapering function.
  \end{description}
\end{description}
The current values of all those parameters may be found through the
\comm{INPUT}{UV\_MAP} command. The main difficulty in the use of the robust
weighting and tapering is the choice of the right parameters for
respectively \texttt{UV\_CELL[2]} and \texttt{UV\_TAPER}. \mapping{} offers
the \com{UV\_STAT} command to guide your choice.
\begin{verbatim}
       1 MAPPING> read uv demo.uvt
       2 MAPPING> uv_stat weight
       3 Robust      Major    Minor     PA            Noise      Sidelobe    
       4               (")      (")     (deg)    (mJy)     (K)       %      
       5    0.10      0.780    0.479     19.8     0.988    0.066  -21.1  18.3
       6    0.18      0.784    0.485     19.5     0.889    0.058  -20.9  19.2
       7    0.32      0.785    0.493     19.3     0.798    0.051  -20.4  20.2
       8    0.56      0.786    0.503     19.3     0.723    0.045  -19.7  21.5
       9    1.00      0.784    0.509     19.4     0.672    0.042  -19.3  23.8
      10    1.78      0.789    0.507     18.3     0.632    0.039  -19.2  26.3
      11    3.16      0.820    0.505     14.8     0.601    0.036  -16.0  30.2
      12    5.62      0.828    0.525     13.1     0.586    0.033  -13.0  32.3
      13   10.00      0.851    0.539     13.2     0.577    0.031  -11.9  34.2
      14   None       0.882    0.559     13.2     0.568    0.029  -10.4  38.2
      15 MAPPING> uv_stat taper
      16 Taper       Major    Minor     PA            Noise      Sidelobe    
      17  (m)          (")      (")     (deg)    (mJy)     (K)       %      
      18   30.00      6.586    3.533     10.6     1.727    0.002  -58.8  26.5
      19   42.43      5.724    2.896     11.7     1.385    0.002  -36.8  25.8
      20   60.00      5.100    2.485     12.8     1.178    0.002  -31.4  24.5
      21   84.85      4.623    2.279     13.2     1.035    0.002  -28.8  22.6
      22  120.00      3.956    2.058     13.2     0.895    0.003  -26.5  23.4
      23  169.71      2.173    1.565     21.8     0.752    0.005  -23.1  27.8
      24  240.00      1.161    1.072    161.1     0.646    0.013  -19.8  32.4
      25  339.41      0.962    0.756     11.9     0.594    0.020  -17.5  35.1
      26  480.00      0.910    0.645     13.2     0.576    0.024  -16.1  36.8
\end{verbatim}
Comments:
\begin{description}
\item[Line 1] Read a \uv{} table in an internal buffer as the
  \com{UV\_STAT} works only on this buffer.
\item[Lines 2-14] Displays the synthesized beam (major, minor, position
  angle), the noise levels (point source in mJy and brightness in K) and
  the level of the sidelobes as a function of the threshold (1st column) to
  be used in the robust weighting method. The usual way to choose the right
  threshold is to select the one that gives a substantially better spatial
  resolution without increasing the noise by more than 10\%.
\item[Lines 15-26] Displays the same parameters as above as a function of
  the tapering distance (1st column) in meter.
\end{description}

\subsection{Typical imaging session}

\begin{verbatim}
       1 read uv demo
       2 input uv_map
       3 uv_stat weight
       4 let weight_mode "UN"
       5 let uv_cell[2] 0.1
       6 input uv_map
       7 uv_map
       8 show beam
       9 show dirty
      10 let map_size 256
      11 uv_map
      12 show beam
      13 show dirty
      14 go wedge
      15 hardcopy demo-dirty
      16 write dirty demo
      17 write beam demo
\end{verbatim}
Comments:
\begin{description}
\item[Step 1] Read the \texttt{demo.uvt} \uv{} table in an internal buffer.
\item[Step 2] Check current state of the variables that control the
  imaging.
\item[Steps 3-6] Select the robust weight mode (step 4) and threshold (step
  5) from the result of the \com{UV\_STAT} command (step 3) and recheck the
  current state of the variables that control the imaging (step 6).
\item[Steps 7-9] Image and plot the dirty beam and image.
\item[Steps 10-13] Tries a larger size of the map as the default imaged
  field-of-view looked too small from previous plots.
\item[Steps 14-15] Make a Post-Script file from the dirty image.
\item[Steps 16-17] Write dirty image and beam in \texttt{demo.lmv} and
  \texttt{demo.beam} files for deconvolution in a future \mapping{}
  session. These steps are optional as you may directly proceed to the
  deconvolution stage without writing the files.
\end{description}

\section{Deconvolution}

\subsection{Philosophy}

Once the dirty beam and the dirty image have been calculated, we want to
derive an astronomically meaningful result, ideally the sky brightness.
However, it is extremely difficult to recover the intrinsic brightness
distribution with an interferometer. But, more fundamentally, the
incomplete sampling of the \uv{} plane implies that there is an infinite
number of intensity distributions which are compatible with the constraints
given by the measured visibilities.  Fortunately, physics allow us to
select some solutions from the infinite number that mathematics authorize.
The goal of deconvolution is thus to find a sensible intensity distribution
compatible with the measured visibilities. To reach this goal,
deconvolution needs 1) some \emph{a priori}, physically valid, assumptions
about the source intensity distribution and 2) as much knowledge as
possible about the dirty beam and the noise properties (in radioastronomy,
both are well known). The best solution would obviously be to avoid
deconvolution, \ie\ to get a Gaussian dirty beam. For instance, the design
of the compact configuration of \ALMA{} has been thought with this goal in
mind. However, this goal is out of reach for today millimeter
interferometer and it will also be for the extended configuration of
\ALMA{}.

The simplest \emph{a priori} knowledge that the user can feed to
deconvolution algorithm is a rough idea of the emitting region in the
source.  The user defines a support inside which the signal is to be found
while the outside is only made of sidelobes. The definition of a support
considerably helps the convergence of deconvolution algorithms because it
decreases the complexity of the problem (\ie\ the size of the space to be
searched for solutions). However, it can introduce important biases in the
final solution if the support exclude part of the sky region really
emitting. Support must be thus used with caution.

\subsection{The family of \clean{} algorithms (\com{HOGBOM}, \com{CLARK},
  \com{MX}, \com{SDI}, \com{MRC}, \com{MULTI})}

Radio astronomy interferometry made a significant step forward with the
introduction of a robust deconvolution algorithm, known as \clean{}, by
\cite{hogbom74}.

\subsubsection{\clean{} ideas}

The family of \clean{} algorithms is based on the \emph{a priori}
assumption that the sky intensity distribution is a collection of point
sources. The algorithms have three main steps
\begin{description}
\item[Initialization] \mbox{}
  \begin{itemize}
  \item of the residual map to the dirty map;
  \item and of the clean component list to a \texttt{NULL} (\ie\ zero)
    value.
  \end{itemize}
\item[Iterative search] for point sources on the residual map. As those
  point sources are found,
  \begin{itemize}
  \item they are subtracted from the residual map;
  \item and then they are logged in the clean component list.
  \end{itemize}
\item[Restoration] of the clean map 1) by convolution of the clean
  component list with the clean beam, \ie\ a Gaussian whose size matches
  the synthesized beam size and 2) by addition of the residual map.
\end{description}

\subsubsection{Stopping criteria}

Several criteria may be used to stop the iterative search of this
``matching pursuit'':
\begin{itemize}
\item The total number of clean components. This is a sanity criterion in
  case the two other ones would be badly tuned.
\item When the maximum of the absolute value of the residual map is lower
  than a fraction of the noise. This stopping criterion is adapted to
  \emph{noise limited situations}, \ie\ when empirical measures of the
  noise in the cleaned image give a value similar to the noise value
  estimated from the system temperatures.
\item When the maximum of the absolute value of the residual map is lower
  than a fraction of the maximum intensity of the original dirty map.  This
  stopping criterion is adapted to \emph{dynamic limited situations}, \ie\ 
  when some part of the source is so intense that the associated side lobes
  are larger than the thermal noise. In this case, any empirical measure of
  the noise in the cleaned image will give a value larger than the noise
  value estimated from the system temperatures.
\end{itemize}
Choosing the good stopping criterion is important because the deconvolution
must go deep enough to be correct but \clean{} algorithms start to diverge
when the noise is cleaned too deep. A good compromise is to clean up to or
slightly below (typically $0.5\sigma$) the noise level.

\subsubsection{Formation of the \clean{} map}

The clean component list may be searched on an arbitrarily fine spatial
grid without too much physical sense as the interferometer has a finite
spatial resolution.  The convolution by the clean beam thus reintroduce the
finite resolution of the observation, information which is missing from the
list of clean component alone. This step is often called \emph{a
  posteriori} regularization.

The shape (principally its size) of the clean beam used in the restoration
step plays an important role. The clean beam is usually a fit of the main
lobe (\ie\ the inner part) of the dirty beam. This ensures that 1) the flux
density estimation will be correct and 2) the addition of the residual map
to the convolved list of clean component makes sense (\ie\ the unit of the
clean and residual maps matches). Super-resolution is the fact of restoring
with a clean beam size smaller that the fit of the main lobe of the dirty
beam. The underlying idea is to get a bit finer spatial resolution.
However, it is a bad practice because it breaks the flux estimation and the
usefulness of the addition of the residual maps. It is better to use robust
weighting to emphasize the largest measured spatial frequencies.

The final addition of the residual map plays a double role. First, it is a
first order correction to insufficient deconvolution. Second, it enables
noise estimate on the cleaned image since the residual image should be
essentially noise when the deconvolution has converged.

\subsubsection{Basic \clean{} algorithms (\com{HOGBOM}, \com{CLARK} and \com{MX})}

The main difference between the different basic \clean{} algorithms is the
strategy for searching the point sources.

\paragraph{\com{HOGBOM}}

The simplest strategy of the iterative search was introduced by
\cite{hogbom74}. It works as follows
\begin{enumerate}
\item Localization of the strongest intensity pixel in the current residual
  map: $\emr{max}(\abs{I_\emr{res}})$.
\item Add $\gamma.\emr{max}(\abs{I_\emr{res}})$ and its spatial position to
  the clean component list.
\item Convolution of $\gamma.\emr{max}(\abs{I_\emr{res}})$ by the dirty
  beam.
\item Subtract the resulting convolution from the residual map in order to
  clean out the side lobes associated to the localized clean component.
\end{enumerate}
$\gamma$ is the loop gain. It controls the convergence of the method. In
theory, $ 0 < \gamma < 2$. High values of $ \gamma$ would in principle give
faster convergence, since the remaining flux at one position is $ \propto
(1-\gamma)^{n_{\mathrm{comp}}}$, where $n_\mathrm{comp}$ is the number of
clean components found at this position. But, in practice, one should use $
\gamma \simeq 0.1 - 0.2$, depending on sidelobe levels, source structure
and dynamic range.  Indeed, deviations (such as thermal noise, phase noise
or calibration errors) from an ideal convolution equation force to use low
gain values in order to avoid non linear amplifications of errors.

An important property of \com{HOGBOM} algorithm is that only the inner
quarter of the dirty image can be properly cleaned when dirty beam and
images are computed on the same spatial grid. Indeed, the subtraction of
the dirty sidelobes associated to any clean component is possible only in
the spatial extent of the dirty beam image. When the user defines a support
(\emph{a priori} knowledge), the cleaned region becomes even smaller than
the inner quarter of the dirty map.

\paragraph{\com{CLARK}}

The most popular variant to the \com{HOGBOM} algorithm is due to
\cite{clark80}. The iterative search for point sources involves minor and
major cycles.
\begin{description}
\item[In minor cycles,] an \com{HOGBOM} search is performed with two
  limitations: 1) Only the brightest pixels are considered in the above
  step 1 and 2) the convolution of the found point sources (step 3 above)
  is done with a spatially truncated dirty beam. Both limitations fasten
  the search but may lead to difficult convergence in cases where the
  secondary side lobes are a large fraction (\eg\ 40\%) of the main side
  lobe.
\item[In major cycles,] the clean components found in the last minor cycle
  are removed in a single step from the residual map in the Fourier plane.
  The use of the Fourier transform enable to clean slightly more than the
  inner quarter of the map.
\end{description}

\paragraph{\com{MX}}

The \com{MX} algorithm, due to \citet{schwab84}, is a variant of the
\com{CLARK} algorithm in which the clean components are removed from the
\uv{} table at each major cycle. This is the most precise way of removing
the found clean components because it avoids aliasing of the dirty
sidelobes. A direct consequence is that this method enable to clean the
largest region of the dirty map. However, this is a relatively slow
algorithm because the imaging step must be redone at each major cycle.

\subsubsection{Advanced \clean{} algorithms to deal with extended
  structures (\com{SDI}, \com{MULTI} and \com{MRC})}

When the spatial dynamic of the imaged source is large (\ie\ when the ratio
of the largest source structure over the synthesized resolution is large),
the basic \clean{} algorithms may (rarely) turn smooth area of the source
into a serie of ridges and stripes. Indeed, when the dirty beam pattern is
subtracted from a smooth feature of the dirty map, the sidelobes patterns
appear in the residual map. The search for the next clean component will
then pick first the pixels in the sidelobes pattern amplifying this
pattern. Several variants of \clean{} has been devised to answer this
problem.

\paragraph{\com{SDI}}

In the \clean{} variant proposed by \cite{steer84}, extended features
(instead of point sources) around the current maximum of the residual map
are selected and removed in a single step. The simplest implementation
redefines the notion of minor and major cycles of the \com{CLARK}
algorithm. In the minor cycles, only the selection of the clean components
is done by including all the pixels in the residual map that rise above a
contour set at some fraction of the current peak level. In major cycles,
all those components are removed together in the Fourier plane. The
\com{SDI} algorithm may be instable is the fraction used for the selection
of clean components is badly chosen.

\paragraph{\com{MRC}}

The Multi Resolution Clean \citep[\texttt{MRC},][]{wakker88} is the first
try to introduce the notion of cleaning at different scales. \com{MRC}
works on two intermediate maps (strictly speaking \com{MRC} is a
double--resolution \clean{} algorithm).  The first map is a smoothed
version of the dirty map and the second map, called difference map, is
obtain by subtraction of the smoothed map from the original dirty map.
Since the measurement equation is linear, both maps can be cleaned
independently (using a smoothed and a difference dirty beam, respectively).
The underlying idea is that extended sources in the dirty map will look
like more "point-like" with respect to the smoothed dirty beam in the
smoothed map. \com{MRC} is faster than the basic \clean{} algorithms
because fewer clean components are needed to reproduce an extended source
feature in the smoothed map than in the original map.

\paragraph{\com{MULTI}}

%% The Multi-scale \clean\ algorithm (\cite{cornwell0X}) has also been
%% designed to improve the performance of \clean\ for extended sources.  It is
%% an straightforward extension of \clean\ that models the sky brightness by
%% the summation of blobs of emission having different size scales.  This
%% algorithms works simultaneously in a range of specified scales.
%% Multi-scale \clean\ can produce good images with a loop gain of 0.5 or even
%% higher.  Since the final image is composed of a summation of blobs each
%% blob should be plausible (without negative brightness). Blobs have axial
%% symmetry to be independent of pixel orientation.  Blob shape in mapping ?
%% What are the scales used in mapping: 0, 2, 4 pixels? Stephane said 3
%% scales.

\subsection{Implementation and typical use}

\subsubsection{Implementation}

In \mapping{}, the variants of the \clean{} algorithms discussed above are
coded as the following commands: \com{HOGBOM}, \com{CLARK}, \com{MX},
\com{SDI}, \com{MULTI} and \com{MRC}. All those commands work on two
internal buffers containing the dirty beam and dirty image. Both buffers
are created directly from \uv{} table through the \com{UV\_MAP} command, or
they can be loaded from files through the \comm{READ}{BEAM} and
\comm{READ}{DIRTY} commands. The behavior of those commands is controlled
through the following common sic variables:
\begin{description}
\item[Iterative search] \mbox{}
  \begin{description}
  \item[\texttt{POSITIVE}] Number of positive clean components to be found
    before enabling the search for negative components. Default is 0.
  \item[\texttt{GAIN}] Loop gain. Default is 0.2, good compromise between
    stability and speed.
  \end{description}
\item[Stopping criteria] \mbox{}
  \begin{description}
  \item[\texttt{NITER}] Maximum number of clean components. Default is 500.
  \item[\texttt{FRES}] Maximum amplitude of the absolute value of the
    residual image. This maximum is expressed as a fraction of the peak
    intensity of the dirty image. Default is 0.
  \item[\texttt{ARES}] Maximum amplitude of the absolute value of the
    residual image. This maximum is expressed in the image units (Jy/Beam).
    Default is 0.
  \end{description}
\item[Support] \mbox{}
  \begin{description}
  \item[\texttt{BLC} and \texttt{TRC}] Bottom Left Corner and Top Right
    Corner of a square support in pixel units. Default is 0, meaning do not
    use such a square support.
  \item[\com{SUPPORT}] A command to interactively define the support where
    to search for clean components. This definition can be stored in a file
    through the \comm{WRITE}{SUPPORT} command and read back in memory from
    the file with the \com{SUPPORT} command. The support definition is
    stored in the \texttt{POLY} sic structure. A side effect is that any
    definition of a polygon (\eg\ through the \comm{GO}{FLUX} command) will
    imply the definition of a support...
    % *** This should be changed JP ***
  \end{description}
\item[Clean beam parameters] \mbox{}
  \begin{description}
  \item[\texttt{MAJOR, MINOR} and \texttt{ANGLE}] FWHM size of the major
    and minor axes (in arcsec) and position angle (in degree) of the
    Gaussian used to restore the clean image from the clean component list.
    Default is all parameters at 0, meaning use the fit of the main lobe of
    the dirty image. Changing the default value of those parameter is
    dangerous.
  \end{description}
\end{description}
Other variables control specific aspects of a subclass of the \clean{}
algorithms:
\begin{description}
\item[\texttt{NMAJOR}] Maximum number of major cycles in all algorithms
  using this notion (\com{CLARK}, \com{MX}, \com{SDI}). Default is 50.
\item[\texttt{BEAM\_PATCH}] Size (in pixel units) of the dirty beam used to
  deconvolve the residual image in minor cycles. It is used in all
  algorithms using the minor cycle notion. Default is 0, meaning *** ? JP
  ***
\item[\texttt{SMOOTH}] *** ? JP ***
\end{description}

\subsubsection{Typical deconvolution session}

\begin{verbatim}
       1 read beam demo
       2 read dirty demo
       3 input clean
       4 hogbom /flux 0 1
       5 show residual
       6 show clean
       7 write clean demo
       8 let name demo
       9 go noise
      10 let ares 0.5*noise
      11 input clean
      12 hogbom /flux 0 1
      13 let niter 2000
      14 input clean
      15 hogbom /flux 0 1
      16 show residual
      17 show clean
      18 for iplane 1 to 10
      19    show clean iplane
      20    support
      21    hogbom iplane /flux 0 1
      22    write support "demo-"'iplane'
      23 next iplane
      24 show residual
      25 show clean
      26 write residual demo
      27 write clean demo
      28 write cct demo
      29 let name demo
      30 let type lmv-clean
      31 go cct
      32 go view
\end{verbatim}
Comments:
\begin{description}
\item[Steps 1-2] Read dirty beam and dirty image from the
  \texttt{demo.beam} and \texttt{demo.lmv} files. Those steps are not
  needed if the dirty beam and image are already stored in the internal
  buffer, \ie\ if you have imaged the \uv{} table just before in the same
  \mapping{} session.
\item[Steps 3-6] Print the current state of the control parameters,
  deconvolve the dirty image using the \com{HOGBOM} algorithm (step 3) and
  look at the results (residual and clean images).  The \texttt{/flux 0 1}
  option pop-up the visualization of the cumulative flux deconvolved as the
  clean components are found.
\item[Steps 8-12] Estimate the empirical noise through the \comm{GO}{NOISE}
  command after this first deconvolution and set the \texttt{ares} stopping
  criterion accordingly. Check that the new value of \texttt{ares} has been
  correctly set (step 11) and restart deconvolution.
\item[Steps 13-17] Increase the number of clean components as the previous
  deconvolution stopped before that the residual image reached the
  \texttt{ares} value. Restart deconvolution and look at results.
\item[Steps 18-25] Tries to improve deconvolution by definition of a
  support per plane and deconvolve this plane accordingly. The support is
  store in a file for memory. The deconvolution results are then displayed.
\item[Steps 26-28] Write residual image, clean image and clean component
  list in \texttt{demo.lmv-res}, \texttt{demo.lmv-clean} and
  \texttt{demo.cct} files for memory.
\item[Steps 29-32] Visualize the cumulative flux as a function of the clean
  component number and visualize the clean spectra cube in an interactive
  way.
\end{description}
Typical deconvolution session using other \clean{} algorithm would look
very similar. The main difference would be the possible tuning of other
control parameters. A deconvolution session using \com{MX} would start
differently as the imaging and deconvolution are done in the same step:
\begin{verbatim}
       1 read uv demo
       2 input uv_map
       3 input clean
       4 mx /flux 0 1
       5 show residual
       6 show clean
       7 write beam demo
       8 write dirty demo
       9 write clean demo
      10 write residual demo
      11 write cct demo
\end{verbatim}
Comments:
\begin{description}
\item[Step 1] Read the \texttt{demo.uvt} \uv{} table in an internal buffer.
\item[Steps 2 and 3] Check current state of the variables that control the
  imaging and deconvolution.
\item[Steps 4-6] Deconvolve and look at the results.
\item[Steps 7-11] Write all the internal buffers for memory.
\end{description}
All the tuning of the typical imaging and deconvolution sessions could be
fitted in this \com{MX} session although they are not repeated here.

\subsection{Comparison and practical advices}

\subsubsection{Comparison of deconvolution algorithms}

\com{HOGBOM} is the basic \clean{} algorithm. It is robust but slow.
\com{CLARK} introduces a faster strategy for the search and removal of
clean component. However, it can be instable when dirty sidelobes are high.
\com{MX} cleans the largest region of the dirty map because the source
removal happens in the \uv{} plane. However, it is slower than \com{CLARK}
because of the repeated imaging step and it shares the possible \com{CLARK}
instabilities because it uses the same search strategy.

\com{HOGBOM}, \com{CLARK} and \com{MX} may introduce artifacts as parallel
stripes in the clean map when dealing with smooth, extended structures.
\com{SDI}, \com{MRC} and \com{MULTI} introduce (in principle) a better
handling of those extended sources. \com{SDI} is a rough attempt while
\com{MRC} and \com{MULTI} introduce the notion of cleaning at different
spatial scales.

\subsubsection{A few (obvious) practical recommendations}
\begin{description}
\item[Map size] Make an image twice the size of the primary beam (\eg\ 
  $2\times55''$ at 90~GHz and $2\times22''$ at 230~GHz for \PdBI{} antenna)
  to ensure that all the area of the primary beam (inner quarter of the
  dirty map) will be cleaned whatever the deconvolution algorithm is used.
  However, avoid making a too large dirty image because the \clean{}
  algorithms will then try to deconvolve region outside the primary beam
  area where the noise dominates.
\item[Support] Start your first deconvolution \emph{without} any support to
  avoid biasing your clean image. If the source is spatially bounded, you
  can define a support around the source and restart the deconvolution with
  this \emph{a priori} information. Be careful to check that there is no
  low signal-to-noise extended structure that could contain a large
  fraction of the source flux outside your support... Avoid defining a
  support too close to the natural edges of your source. Indeed,
  deconvolving noisy regions around your source is advisable because it
  ensures that you do not biased your deconvolution.
\item[Stopping criterion] Choose the right stopping criterion.
  \begin{itemize}
  \item Estimate an empirical noise on your first deconvolved cleaned image
    with \comm{GO}{NOISE}.
  \item If this empirical noise value is larger the value computed from the
    visibility weights (This noise value is one of the output of the
    \com{UV\_MAP} command), your observation is probably dynamic limited,
    \ie\ you have a bright source whose dirty sidelobes are much larger
    that the thermal noise. In this case use, set \texttt{ARES} to 0 and
    \texttt{FRES} to a fraction which depends on the sidelobe level of your
    dirty beam.
  \item Else you are in the noise limited case. Set \texttt{FRES} to 0 and
    \texttt{ARES} to a fraction of the empirical noise value (typically
    0.5).
  \end{itemize}
\item[Convergence checks] Ensure that your deconvolution converge by
  checking that
  \begin{itemize}
  \item The cumulative flux as a function of the number of clean component
    has reached a roughly constant level (use \verb|\FLUX| option of the
    deconvolution commands to see this curves).
  \item The residual map looks like noise where the source appears in the
    clean map.
  \end{itemize}
  Else change the values of the stopping criterion, in particular the
  number of clean components (\texttt{NITER}).
\item[Deconvolution methods] If you want a robust result in all cases,
  start with \com{HOGBOM}. If you prefer obtaining a quick result, use
  \com{CLARK} but you then first need to check that the dirty sidelobes are
  not too large on the dirty beam. If you obtain stripes in your clean
  image:
  \begin{itemize}
  \item First check that there is no spurious visibilities that should be
    flagged.
  \item Then check that your deconvolution converged.
  \item If it is clear that you have an extended source structure, you
    should first ask yourself whether you are in the wide-field imaging
    case and act accordingly (see next chapter). Else you can try a
    \clean{} variant which better deals with cases that implies a large
    spatial dynamic. This is rare at \PdBI{}.
  \end{itemize}
\item[Outside help] Always consult an expert until you become one.
\end{description}

\chapter{Wide-field imaging and deconvolution}

We are often asked why the wide-field imaging and deconvolution steps are
more difficult than their equivalent for single-field. The main answer is
that doing wide-field observations with an interferometer is kind of
paradoxical. Indeed, (sub)millimeter interferometers are before all tuned
to get the best possible spatial resolution. A natural consequence is the
lack of measurement of the low spatial frequencies which are extremely
important in wide-field observations. Hence the paradox.  In addition, the
first goal of the current generation of (sub)millimeter interferometer was
to demonstrate the feasibility of routine interferometric observations in
the (sub)millimeter range. The need of doing wide-field imaging at high
spatial resolution has thus been recognized only after the success of high
spatial resolution single-field imaging. This makes the implementation of
wide-field imaging more difficult. The situation will improve with ALMA
because wide-field imaging has been included from scratch in its design. It
remains that wide-field imaging pushes (sub)millimeter interferometers to
their limits.

From a software point-of-view, we always try to hide the technical
complexity in more user-friendly tools as soon as our experience increases.
However, because of its paradoxical nature, wide-field imaging with an
interferometer implies a knowledgeable use of those tools.

\section{General considerations about wide-field imaging}

The measurement equation for a millimeter interferometer is to a good
approximation (after calibration)
\begin{equation}
  V(u,v) = \mbox{FT}\cbrace{B_\emr{primary}.I_\emr{source}}(u,v)+N
\end{equation}
where $\mbox{FT}\cbrace{F}(f)$ is the bi-dimensional Fourier transform of
the function $F$ taken at the spatial frequency $f$, $I_\emr{source}$ the
sky intensity, $B_\emr{primary}$ the primary beam of the interferometer
(\ie\ a Gaussian of FWHM the natural resolution of the single-dish antenna
composing the interferometer), $N$ some thermal noise and $V(u,v)$ the
calibrated visibility at the spatial frequency $u,v$. The product of the
sky intensity by the primary beam, which ``quickly'' decreases to zero,
implies that an interferometer looking at a particular direction of the sky
will have its field-of-view limited by the size of the primary beam.
 
To image a field-of-view larger than the primary beam size, the antennae of
an interferometer will be successively pointed in different directions of
the sky typically separated by half the size of the primary beam. This
process is called mosaicing and the result requires specific imaging and
deconvolution steps. Another possibility is to acquire data as the
interferometer antenna continuously slew through a portion of the sky. This
second observing mode is called interferometric On-The-Fly (OTF). While
mosaicing is standard at \PdBI{} (see section~\ref{sec:mosaicing}), some
efforts are currently done to commission the OTF observing mode.

Mosaicing and OTF clearly belongs to wide-field imaging. However
considerations about wide-field imaging start as soon as the size of the
source is larger than about 1/3 to 1/2 of the interferometer primary beam.
Indeed, a multiplicative interferometer (\eg\ all interferometer in the
(sub)mm range) is a bandpass instrument, \ie\ it filters not only the large
spatial frequencies (this is the effect of the finite resolution of the
instrument) but also the small spatial frequencies (all the frequencies
smaller than typically the diameter of the interferometer antennas). An
important consequence is that a multiplicative interferometer do \emph{not}
measure the total flux of the observed source. This derives immediately
from the following property of the Fourier Transform: The Fourier transform
of a function evaluated at zero spacial frequency is equal to the integral
of your function. Adapting this to our notation, this gives
\begin{equation}
  V(u=0,v=0) \stackrel{\mbox{FT}}{\rightleftharpoons} \sum_{ij~\in~\emr{image}} \cbrace{B_\emr{primary}.I_\emr{source}}_{ij}.
\end{equation}
\ie\ the visibility at the center of the \uv{} plane is the total intensity
of the source. As a multiplicative interferometer filters out in particular
$V(u=0,v=0)$, the information about the total flux of the observed source
is lost. In summary, a multiplicative interferometer only gives information
about the way the flux of the source is distributed in the spatial
frequencies larger than the primary beam but no information about the total
flux.

Deconvolution algorithms use, in one way or another, the information of the
flux at the smallest \emph{measured} spatial frequencies to extrapolate the
total flux of the source. This works correctly when the size of the source
is small compared to the primary beam of the interferometer. The extreme
case is a point source at the phase center for which the amplitude of all
the visibilities is constant and equal to the total flux of the source:
Extrapolation is then exact. However, the larger the size of the source,
the worst the extrapolation, which then underestimates the total source
flux. This is the well-known problem of the missing flux that observers
sometimes note when comparing the flux of the source delivered by a mm
interferometer with the flux observed with a single-dish antenna. The
transition between right and wrong extrapolation is not well documented. It
depends on the repartition of the flux with spatial frequencies but also of
the signal-to-noise ratio of the measured spatial frequencies. It is often
agreed that the transition happens for sizes between 1/3 and 1/2 of the
interferometer primary beam. For larger source size, information from a
single-dish telescope is needed to fill in the missing information and to
thus obtain a correct result. This is the object of
section~\ref{sec:short-spacings}.

\section{Mosaicing}
\label{sec:mosaicing}

\subsection{Observations and processing}

In a single-field observation, an interferometer tracks a particular
direction of the sky, named the phase center. The portion of the sky which
can be image around this direction is directly linked to the size of the
primary beam. The easiest way to image field-of-view larger than the
primary beam size is to track one direction of the sky after another until
the desired field-of-view is filled with small images made around many
different tracking directions. This observing mode is called mosaicing and
the tracked observations which constitute the mosaic are called fields.

There are many constraints to optimize mosaicing.
\begin{description}
\item[Nyquist sampling of the mosaic field-of-view and mosaic pattern] The
  mosaic field-of-view must at least be Nyquist-sampled to obtain a
  reliable image. Each observed field can produce a reliable image of the
  same shape than the primary beam, \ie\ a circular Gaussian (This assumes
  that the short-spacing problem has been solved). Nyquist sampling thus
  implies that the mosaic fields follow an hexagonal compact pattern as
  this ensures a distance between all neighboring fields of half the
  primary beam size. When the total observing time is fixed, Nyquist
  sampling is the best compromise between sensitivity and total
  field-of-view. Indeed, the distance between neighboring fields could be
  less (in which case the mosaic would be oversampled) than half the
  primary beam size. In this case, the sensitivity on each pixel of the
  final image would increase with the share of the time spent to observe
  this direction.
\item[Uniform imaging properties and quick loop around the fields] Getting
  uniform imaging properties is a desirable feature in the final result.
  This implies that a \uv{} coverage and a noise level as uniform as
  possible among the different fields. Quickly looping around the different
  fields is the easiest way to reach this goal. However, dead time to
  travel from one field to another must almost be minimized. At \PdBI{},
  the compromise is to pause at least 1 minute on each field and to try to
  loop over all the fields between two calibrations every 20 minutes.
  Hence, mosaic done in a single observing run is made of at most 20
  fields.  Larger mosaic must be observed by group of fields in different
  observing runs.
\end{description}

After calibration and production of an image per field, two different
processing flow are possible.
\begin{enumerate}
\item The field are deconvolved independently and the clean image are
  combined to obtain the final image.
\item The dirty images are combined together and a global deconvolution
  happen on the combined dirty image.
\end{enumerate}
While solution 1 is simpler to implement, solution 2 gives a better
deconvolution because 1) information about sources at the edges of and
individual field is furnished by the other fields and 2) the signal coming
from the different field add up to get a better signal-to-noise ratio. The
next two sections describes the particularities of mosaic imaging and
deconvolution.

\subsection{Imaging (\com{UV\_MAP} and \comm{RUN}{MAKE\_MOSAIC})}

When combining together (dirty or clean) images, it is important to correct
the primary beam attenuation to avoid modulation of the signal in the
combined image. If we forget for the moment the dirty beam convolution, the
images associated to each fields are noisy measurement of the same quantity
(the sky brightness distribution) weighted by the primary beam. The best
estimation of the measured quantity is thus given by the least mean square
formula
\begin{equation}
  \label{eq:mosaic:signal}
  \displaystyle %
    M(\alpha,\delta) = \frac{\displaystyle\sum\nolimits_i \frac{B_i(\alpha,\delta)}{\sigma_i^2}\,F_i(\alpha,\delta)}
      {\displaystyle\sum\nolimits_i \frac{B_i(\alpha,\delta)^2}{\sigma_i^2}},
\end{equation}
where $M(\alpha,\delta)$ is the brightness of the dirty/cleaned mosaic
image in the direction $(\alpha,\delta)$, $B_i$ are the response functions
of the primary antenna beams in the tracking direction of field $i$, $F_i$
are the brightness distributions of the individual dirty/cleaned maps, and
$\sigma_i$ are the corresponding noise values. As may be seen on this
equation, the intensity distribution of the mosaic is corrected for primary
beam attenuation. This implies that noise is inhomogeneous. Indeed, if
$N(\alpha,\delta)$ is the noise distribution and $\sigma(\alpha,\beta)$ is
its standard deviation in the direction $(\alpha,\beta)$, we have
\begin{equation}
  \label{eq:mosaic:noise}
    N(\alpha,\delta) = \frac{\sum\nolimits_i \frac{B_i(\alpha,\delta)}{\sigma_i^2}\,N_i(\alpha,\delta)}
      {\sum\nolimits_i \frac{B_i(\alpha,\delta)^2}{\sigma_i^2}},
\end{equation}
and
\begin{equation}
  \label{eq:mosaic:sigma}
    \sigma(\alpha,\delta) = %
    \frac{\sqrt{\sum\nolimits_i \frac{B_i(\alpha,\delta)}{\sigma_i^2}}}
    {\sum\nolimits_i \frac{B_i(\alpha,\delta)^2}{\sigma_i^2}} = %
    \frac{1}{\sqrt{\sum\nolimits_i \frac{B_i(\alpha,\delta)^2}{\sigma_i^2}}}
\end{equation}
Not only, the noise strongly increases near the edges of the mosaic
field-of-view. But also, the center of each field is contaminated by
increased noise level coming from the external regions of the neighboring
fields. Indeed, the noise corrected for the primary beam attenuation is
largely increasing where the primary beam is going to zero. To limit these
effects, both the primary beams used in the above formula and the resulting
mosaic are truncated.

\subsection{Deconvolution (\com{MOSAIC}, \com{HOGBOM}, \com{CLARK} and \com{SDI})}

Standard \clean{} algorithms must be slightly modified to work on a dirty
mosaics. Indeed, the use of truncated primary beam in the above equations
is only a first order measure to avoid noise artifacts. However, the noise
level still increases at the edges of the mosaic, implying that at some
point the \clean{} algorithms will confuse noise peaks at the mosaic edges
with true signal. To avoid this, the iterative search is made on a
signal-to-noise image $M(\alpha,\beta)/\sigma(\alpha,\beta)$ instead of the
residual image. At the restoration step, the clean component list is used
to produce the residual map and clean map. Nothing particular is done with
the remaining signal-to-noise image.

\subsection{Implementation and typical use}

\subsubsection{Implementation}

The typical processing of \PdBI{} mosaics has four main steps
\begin{description}
\item[Creation of \uv{} tables] The convention inside \mapping{} is that
  the visibilities associated to one field of the mosaic are grouped in one
  \uv{} file whose name is made of a generic part plus the field number.
  For instance, a mosaic of 7 fields would imply the presence in the same
  working directory of 7 \uv{} table, \eg\ \texttt{demo-1.uvt},
  \texttt{demo-2.uvt}, \texttt{demo-3.uvt}, ... \texttt{demo-7.uvt}. This
  is the user responsibility to enforce this at the time of creation of the
  \uv{} table in \clic{}.
\item[Imaging of individual fields] Each field (\uv{} table) must then be
  individually imaged using the standard \com{UV\_MAP} command. This is in
  this step that the fields are put in the larger framework of the mosaic,
  \ie\ they are placed in an image large enough to contain the whole
  mosaic. This implies that
  \begin{enumerate}
  \item The user must feed the size of the final mosaic through the
    \texttt{map\_size} sic variable because the \com{UV\_MAP} command has
    no information about the mosaic as it works on one field after the
    other.
  \item The projection (\ie\ phase) center will have to be shifted in this
    step with the use of the \texttt{UV\_SHIFT}, \texttt{MAP\_RA} and
    \texttt{MAP\_DEC} variables. Indeed, the observing setup of a mosaic at
    \PdBI{} implies that each field has its own projection center (the sky
    tracking direction of the field).  The new value of the phase center
    will be stored in the \texttt{A0} and \texttt{D0} values of the header
    while the \texttt{RA} and \texttt{DEC} values will keep the tracking
    direction of the observation. Indeed, the latter information is needed
    to correct for the primary beam attenuation and to form the mosaic.
    The new phase center can be arbitrarily chosen but it is recommended to
    choose it around the middle of the mosaic.
  \end{enumerate}
  At the end of this step, the dirty beams and images must be stored in
  files (\eg\ \texttt{demo-1.beam}, \texttt{demo-2.beam}, ...
  \texttt{demo-7.beam} and \texttt{demo-1.lmv}, \texttt{demo-2.lmv}, ...
  \texttt{demo-7.lmv}) in the same directory.
\item[Creation of the mosaic] The \com{MAKE\_MOSAIC} task linearly combines
  the dirty images using the least square formula~\ref{eq:mosaic:signal}
  into a single dirty image named \texttt{demo.lmv} and it creates a weight
  image ($1/\sigma^2$) stored in the \texttt{demo.weight} file. In fact, to
  simplify the deconvolution bookkeeping, the \texttt{demo.lmv} contains
  only the numerator of formula~\ref{eq:mosaic:signal}. As the denominator
  is equal to the weight image, formula~\ref{eq:mosaic:signal} can easily
  be retrieved by dividing the dirty image by the weight image. *** Is this
  fully true? JP *** The \com{MAKE\_MOSAIC} task also gathers the different
  dirty beam as different planes of the \texttt{demo.beam} file. Finally,
  it creates a data cube of primary beams (\texttt{demo.lobe}). The four
  files created at this step are needed during the deconvolution. Two input
  parameters of the \com{MAKE\_MOSAIC} task are important for mosaicing:
  the primary beam width (FWHM), and the truncation threshold of the
  primary beam. It is recommended to use a relatively high value for this
  threshold, typically 0.2, to avoid contaminating adjacent field in case
  of pointing errors.
\item[Deconvolution of the mosaic] The \com{HOGBOM}, \com{CLARK} and
  \com{SDI} variants of the \clean{} algorithm has been adapted to treat
  mosaics. The same commands are used to deconvolve a single field or a
  mosaic. The change of behavior of the \clean{} algorithms is visualize
  through the change of prompt from \texttt{MAPPING>} to \texttt{MOSAIC}.
  The toggle from single field to mosaic is done by the \com{MOSAIC}
  command. Note that the use of the \comm{READ}{PRIMARY} command also
  automatically switch on the mosaic mode. All standard control variables
  for a single-field deconvolution control the same aspect of a mosaic
  deconvolution. Two additional variables are used for mosaic deconvolution
  \begin{description}
  \item[\texttt{SEARCH\_W}] *** ? JP ***
  \item[\texttt{RESTORE\_W}] *** ? JP ***
  \end{description}
  Finally, note that the mosaic deconvolution produces sky brightness
  images while single-field deconvolution produces images attenuated by the
  primary beam.
\end{description}
An additional subtlety of the current \mapping{} implementation of
mosaicing is that \mapping{} assumes that the individual fields of the
mosaic have similar noise level. This is why combining two mosaics observed
at different moments is not straightforward.

\subsubsection{Typical mosaicing session}

\begin{verbatim}
       1 input uv_map
       2 let map_size 256 512
       3 let map_cell 0.5
       4 let uv_shift yes
       5 let map_ra  20:39:10
       6 let map_dec 68:01:20
       7 input uv_map
       8 for ifield 1 to 20
       9    let name "demo-"'iplane'
      10    read uv 'name'
      11    uv_map
      12    write beam  'name'
      13    write dirty 'name'
      14 next ifield
      15 run make_mosaic
      16 read beam demo
      17 read primary demo
      18 read dirty demo
      19 input clean
      20 hogbom /flux 0 10
      21 show residual
      22 show clean
      23 write residual demo
      24 write clean demo
      25 write cct demo
      26 let name demo
      27 go view
\end{verbatim}
Comments:
\begin{description}
\item[Steps 1-7] Define the mosaic size, pixel size and projection center.
\item[Steps 8-14] Image each field individually following the \mapping{}
  name convention.
\item[Step 15] Combine the different fields into the dirty mosaic.
\item[Steps 16-22] Read the primary beams, dirty beams, dirty image and
  weight image into internal buffers. Deconvolve and visualize the results.
\item[Steps 23-27] Write the results on disk for memory and interactively
  visualize the deconvolve data cube.
\end{description}

\section{Short spacings (\comm{RUN}{UV\_SHORT} and \comm{RUN}{UV\_ZERO})}
\label{sec:short-spacings}

Let's note $D$ the diameter of the single-dish antenna ($D = 30$m for the
IRAM-30m telescope) used to produce the short-spacing information and $d$
the diameter of the interferometer antennas ($d = 15$m for \PdBI{}). We
already mentioned that a multiplicative interferometer filters out all the
spatial frequencies smaller than $\sim d$ meters. When this information is
needed to get reliable results, the source should also be observed with a
single-dish antenna to produce the missing information.  The single-dish
antenna furnishes information about all spatial frequencies up to $\sim D$
meters (but this information is weighted by the single-dish beam shape,
\ie\ high frequencies are measured with a worse signal-to-noise ratio than
low frequencies). To recover all the information at spatial frequencies
smaller than $\sim d$ meters, the diameter of single-dish antenna must be
larger or equal to the diameter of the interferometer antennae: $D \ge d$.

\subsection{Algorithms to merge single-dish and interferometer information}

The measurement equations of a single-dish and an interferometer are quite
different from each other. Indeed, the measurement equation of a
single-dish antenna is
\begin{equation}
  I_\emr{meas}^\emr{sd} = B_\emr{sd} \star I_\emr{source} + N,
\end{equation}
\ie\ the measured intensity ($I_\emr{meas}^\emr{sd}$) is the convolution of
the source intensity distribution ($I_\emr{source}$) by the single-dish
beam ($B_\emr{sd}$) plus some thermal noise, while the measurement equation
of an interferometer can be rewritten as
\begin{equation}
  I_\emr{meas}^\emr{int} = B_\emr{dirty} \star \cbrace{B_\emr{primary}.I_\emr{source}} + N,
\end{equation}
\ie\ the measured intensity ($I_\emr{meas}^\emr{int}$) is the convolution
of the source intensity distribution times the primary beam
($B_\emr{primary}.I_\emr{source}$) by the dirty beam ($B_\emr{dirty}$) plus
some thermal noise. $B_\emr{sd}$ has very similar properties than
$B_\emr{primary}$ and very different properties than $B_\emr{dirty}$.  In
radioastronomy, $B_\emr{sd}$ and $B_\emr{primary}$ both have Gaussian
shapes. Moreover, the fact that we will use the single-dish information to
produce the short-spacing information filtered out by the interferometer
implies that $B_\emr{sd}$ and $B_\emr{primary}$ have similar full width at
half maximum. Now, $B_\emr{dirty}$ is quite far from a Gaussian shape with
the current generation of interferometer (in particular, it has large
sidelobes) and the primary side lobe of $B_\emr{dirty}$ has a full width at
half maximum close to the interferometer resolution, \ie\ much smaller than
the FWHM of $B_\emr{sd}$.

Merging both kinds of information obtained from such different measurement
equations thus asks for a dedicated processing. There are mainly two
families of short-spacing processing: The hybridization and the
pseudo-visibility techniques.

\subsubsection{Hybridization technique}

In this family, most of the processing is done on the interferometric data
alone. Indeed, the interferometric data is deconvolved and corrected for
the primary beam contribution to obtain
\begin{equation}
  I_\emr{clean}^\emr{int} = B_\emr{clean} \star I_\emr{source} + N',
  \label{eq:clean}
\end{equation}
where $B_\emr{clean}$ is a Gaussian of FWHM equal to the interferometer
resolution and $N'$ is some thermal noise corrected for the primary beam
contribution.  Two main facts are hidden in this formulation: 1) the
field-of-view of the observation is obviously limited to the observed
portion of the sky and 2) more importantly, the lack of short-spacings has
not yet been overcome and a better formulation would be
\begin{equation}
  I_\emr{clean}^\emr{int} = \mbox{Highpass-filter}\cbrace{B_\emr{clean} \star I_\emr{source}} + N'.
\end{equation}
The simplicity of equation~\ref{eq:clean} is thus slightly misleading but
we will keep it for the sake of simplicity. The hybridization method
consists in combining two images ($I_\emr{meas}^\emr{sd}$ and
$I_\emr{clean}^\emr{int}$) in the \uv{} plane.
\begin{enumerate}
\item Both images are first spatially regridded on the same fine grid.
\item The FFT of those two images are computed, and linearly combined by
  selecting the low spatial frequencies from FFT($I_\emr{meas}^\emr{sd}$)
  and the high spatial frequencies from FFT($I_\emr{clean}^\emr{int}$).
  The transition between low and high spatial frequency
\item The result is FFTed back to the image plane to produce a final,unique
  image, which takes into account both single-dish and interferometric
  information.
\end{enumerate}
The method has the following free parameters: the transition radius and the
detailed shape of that transition.  To avoid discontinuity, the transition
shape is chosen to be reasonably smooth. The spatial frequency of
transition is generally chosen to the smallest spatial frequency reliably
measured by the interferometer (\eg\ about 20~m for \PdBI{}).

\subsubsection{Pseudo-visibility technique}

\paragraph{General description}

In this family, the single-dish information is heavily processed before
merging with the interferometric information. The basic idea is to produce
from the single-dish observations pseudo-visibilities similar to the ones
that would be produced by the interferometer if they were not filtered out.
\begin{enumerate}
\item The Single-Dish measurements are re-gridded and then FFTed into the
  \uv{} plane.
\item The data are deconvolved of the single-dish beam ($B_\emr{sd}$)
  convolution by division by its Fourier Transform (truncated to the
  antenna diameter).
\item The data are FFTed back to the image plane and multiplied by the
  interferometer primary beam, $B_\emr{primary}$.
\item The result is FFTed again in the \uv{} plane where the visibilities
  are sampled on a regular grid.
\item In the case of a mosaic, the two last operations are performed for
  each pointing center.
\end{enumerate}
Using the properties of the Fourier transform, we can rewrite the
measurement equation of an interferometer as
\begin{equation}
  V(u,v) = \cbrace{\mbox{FT}(B_\emr{primary}) \star \mbox{FT}(I_\emr{source})}(u,v)+N.
\end{equation}
This equation means that the visibility measured by an interferometer at
the spatial frequency $(u,v)$ is the convolution of the Fourier transform
of the source intensity distribution by the Fourier transform of the
primary beam. Hence, to get pseudo-visibilities truly consistent with
interferometric visibilities, we must be able to reliably compute the
convolution by the Fourier transform of the primary beam. This implies that
we can compute pseudo-visibilities only for spatial frequencies lower than
$D-d$. The use of the IRAM-30m to produce the short-spacing information of
the \PdBI{} is thus ideal as it enables to recover pseudo-visibilities up
to 15~m ($=30\,\mbox{m}-15\,\mbox{m}$). Once the pseudo-visibilities have
been computed, they are merged with the interferometric visibilities and
standard imaging and deconvolution are then applied to the merged data set.

\paragraph{An important subset: The zero spacing}

An important subset of the pseudo-visibility method is the production of
only the zero spacing. Indeed, the zero spacing is just the total flux of
the observed field-of-view. Hence, if the observed field-of-view is small
enough to fit in the single-dish beam (this is in particular always the
case if $D = d$), a single spectra observed with the single-dish telescope
in the direction of the interferometer phase center may be used as zero
spacing, only a scaling from Kelvin to Jansky is needed. This is the poor
man's solution as only part of the short spacing information is recovered
by this technique.

\paragraph{Single-dish vs interferometer weight}

In all cases involving short spacings, the relative weight of the single
dish data to interferometer data is critical. Within the restrictions
imposed by the noise level, this relative weight is a free parameter. It is
all the more important that the Fourier transform of the \uv{} plane
density of weights is the dirty beam, a key parameter of the deconvolution.
The general goal is to have a dirty beam as close as possible to a
Gaussian. As the Fourier transform of a Gaussian is a Gaussian, we search
for obtaining a \uv{} plane density of weights as close as possible to a
Gaussian. In general, the short spacing frequencies are small compared to
the largest spatial frequency measured by an interferometer. This implies
we can use the linear approximation of a Gaussian, \ie\ a constant, in the
range of frequencies used for the short spacing processing. We thus end up
with the need to match (as far as possible) the Single-Dish and
interferometric densities of weights in the \uv{} plane. In practice, we
compute the density of weights from the single-dish in a \uv{} circle of
radius $1.25 d$ and we match it to the averaged density of weights from the
interferometer in a \uv{} ring between 1.25 and $2.5 d$. Experience shows
that this gives the right order of magnitude for the relative weight and
that a large range of relative weight around this value gives very similar
final results.

When processing IRAM-30m data to combine to \PdBI{} data, this criterion
implies a large down-weighting of the IRAM-30m data which may make think
that too much observing time was used at the IRAM-30m data. However, just
using the above criterion to determine the observing time needed at the
IRAM-30m would in general lead to very low signal-to-noise ratio of the
single-dish map. In such a case, it is very difficult to detect problems
which would translate in strong artifacts in the IRAM-30m + \PdBI{}
combination. We recommend to ask for enough IRAM-30m time to get a
\emph{median} signal-to-noise ratio of 5 on the single-dish map. This ratio
should be achieved for all velocity channels of interest (which may include
the line wings).

\subsubsection{Comparison}

The simplicity of the hybridization technique is its main advantage. It is
simple to understand and simple to implement. However, this method works
badly in practice because because it is truly difficult to obtain a
reliable deconvolution of interferometric data alone when short-spacing
information is important. Indeed, a multiplicative interferometer filters
in particular the zero spacing. This implies that the total flux in the
dirty image is zero (\ie\ as much negative as positive flux in the dirty
image) but that the dirty beam integral is also zero (\ie\ as much negative
as positive sidelobes). When we add the short-spacing information (and in
particular the zero spacing) through the pseudo-visibility method, we
enforce positivity of the dirty image total flux and of the dirty beam
integral. It is well-known that trying to deconvolve a mosaic built only
with interferometric data is quite difficult. It almost always requires the
definition of support where the \clean{} algorithms can search for clean
components with the clear risk to bias the final result. In contrast,
adding the short-spacing information through pseudo-visibilities enables an
almost straightforward \clean{} deconvolution \emph{without} the need of
any support.

For the sake of illustration, let's assume an intensity distribution made
of a large scale structure (\eg{} a uniform intensity) superimposed with a
small scale distribution both in emission and absorption. A multiplicative
interferometer will filter out the uniform intensity distribution. If there
is no additional zero spacing information, the uniform intensity
distribution is completely lost with the important consequence that the
final deconvoled image will have positive (emission) and negative
(absorption) structures. Trying to reproduce both negative and positive
structures is one of the most difficult task for deconvolution algorithms.
Algorithms of the MEM family enforce positivity in the deconvolved image.
In addition, the presence of large negative structures makes instable the
algorithms of the \clean{} family (because it is difficult to distinguish
between negative absorption structures and negative sidelobes of emission
structures). Only the definition of support around positive emission peaks
succeed to stabilize the \clean{} algorithms with the drawback of biasing
the result.

Both kind of algorithms (hybridization and pseudo-visibility) are
implemented in \gildas{}. However, we strongly recommend to use the
pseudo-visibility algorithm. That's why only the pseudo-visibility method
is packaged in a user-friendly way (\eg\ through the \texttt{Short Space
  Processing} widget). \citet{pety01b,pety01a,pety01c} showed through
simulations that 1) the pseudo-visibility algorithm implemented in
\gildas{} enable extremely reliable results (fidelities of a few thousands)
on ideal observations and 2) the accuracy of the wide-field imaging is
limited by pointing errors, amplitude calibration errors and atmospheric
phase noise (and not by the used algorithms), even for ALMA.

\subsection{Practical considerations}

\subsubsection{When are short-spacing information needed?}

\begin{itemize}
\item If the source size is smaller than 1/3 the primary beam size,
  short-spacing information is superfluous.
\item If the source size is between 1/3 and 1/2 the primary beam size of
  \PdBI{} antennae, a single spectra obtained at the IRAM-30m telescope in
  the direction of the source can be used to produce the zero spacing
  information with the \com{UV\_ZERO} task. Indeed, the IRAM-30m diameter
  being twice the diameter of the \PdBI{} antenna, all the flux of the
  source will be measured by a single IRAM-30m spectrum only if the size of
  the source is smaller than 1/2 the primary beam size of \PdBI{} antennae.
\item If the source size is larger than 1/2 the primary beam size of
  \PdBI{} antennae, short-spacing information under the form of an IRAM-30m
  map is almost always mandatory. The only exception could be wide-field
  imaging of a region made of unresolved or small (compared to the primary
  beam size) sources as it may happen when mapping close-by external
  galaxies for instance. However, adding short-spacing will anyway help the
  deconvolution. In case of doubt, always add short-spacing information.
\end{itemize}

\subsubsection{How to optimize single-dish observations?}

One of the main difficulty of the short-spacing problematic is the need of
observations from a single-dish telescope different from the
interferometer. In this respect, the IRAM-30m and \PdBI{} are very
complementary. Nevertheless, when observing with the single-dish telescope,
a few precautions are needed to avoid contaminating the interferometric
data with possible artifacts of single-dish data.
\begin{itemize}
\item The field-of-view of the single-dish map must be twice the
  field-of-view covered by the mosaic. The only exception to this rule
  happens when the source intensity decreases to zero in a smaller
  field-of-view. Indeed, there is no point in observing an empty sky.
\item The observing strategy must enforce Nyquist sampling (or better) of
  the source at the resolution of the single-dish telescope.
\item A particular care should be taken of the pointing, tracking and
  amplitude calibration and baseline removal as those are critical issues
  in obtaining a high quality single-dish map to produce short-spacing
  information. For instance, data with too large tracking errors should be
  discarded.
\item We advise to make many On-The-Fly coverages of the observed
  field-of-view to get homogeneous observing conditions. Scanning in
  perpendicular directions is needed to decrease stripping.
\end{itemize}
Sometimes, single-dish telescope time is scarce and some of the above
criteria can not be fulfilled. In those cases, you can still try to use
your single-dish observations and our algorithm will try to make its best
to get a sensible result. However, any artifact in the combination may
directly come from wrong single-dish observations. In other words, do
\emph{not} blame the software unless you are sure of the quality of the
quality of your single-dish (and interferometric) observations...

\subsubsection{How to use your single-dish observations?}

Our algorithm to produce the short-spacing information is coded in the
\com{UV\_SHORT} task. This task have about 25 input parameters which are
not always intuitive to fill in (in particular the relative weight between
single dish and interferometric data). We thus wrote a \sic{} procedure
which wraps up most of the task input parameters according to the context.
This procedure is driven by the widget called \texttt{short-spacings
  processing} in the main \mapping{} menu. Although you have the
possibility to access all the control parameters of the \com{UV\_SHORT}
task through this widget, you should have only the file names and the
single-dish data unit to fill in, all other parameters being guessed by the
procedure.

This task starts from the data format produced by the \class{} \com{TABLE}
command. Basically, this is a GDF table containing one line per spectrum,
the columns representing the lambda offset, beta offset, weight, and the
spectrum intensities. This format is subject to change: Please, refer to
the \com{TABLE} documentation for up-to-date information. At least two
characteristics of this table must be tuned on the characteristics of the
interferometric observations:
\begin{description}
\item[The velocity axis] because all the computations are done plane by
  plane without velocity resampling.
\item[The center of projection] because all the computations are done using
  the offset to this center.
\end{description}
To do this, the user needs to work both in \mapping{} and \class{}.
\begin{description}
\item[Inside \mapping,] both informations can be found with the following
  commands
\begin{verbatim}
       1 read uv field-1
       2 uv_map
       3 write dirty field-1
       4 header field-1.lmv
\end{verbatim}
  Comments:
\begin{description}
\item[Steps 1-3] Images the first field of a mosaic because the information
  about the velocity axis will be much easier to dig up in the dirty cube
  \texttt{field-1.lmv} than in the \uv{} table \texttt{field-1.uvt}.
\item[Step 4] Displays the header as follow:
\end{description}
\begin{verbatim}
       1  File : field-1.lmv                                        REAL*4
       2  Size      Reference Pixel        Value                  Increment
       3     256   129.0000000000000   0.000000000000000   -1.5514037841057871E-06
       4     256   129.0000000000000   0.000000000000000    1.5514037841057871E-06
       5      49   25.50000000000000   10.50000000000000    0.2000000029802322
       6       1   0.000000000000000   0.000000000000000    0.000000000000000
       7 ...
       8  Axis 1     A0       05:40:54.270        Axis 2     D0      -02:28:00.00
       9 ...
\end{verbatim}
\begin{description}
\item[Line 8] Indicates that the axes 1 and 2 are space coordinates around
  the phase center $\alpha_{2000} = 05:40:54.270$, $\beta_{2000}
  =-02:28:00.00$.
\item[Lines 3-6] Describes the axes and in particular the velocity axis as
  line 5, \ie\ 49 channels of 0.2~km/s width, the velocity of the 25.5
  channel being 10.5~km/s.
\end{description}
\item[Inside, \class] you need to type the following commands to align the
  characteristics of your single-dish data to the above values
\begin{verbatim}
       1 file in  single-dish-reduced.30m
       2 file out single-dish-reprojected.30m single
       3 set level 5
       4 set system equatorial 2000.00
       5 find
       6 for ientry 1 to found
       7    get next
       8    modify position 05:40:54.270 -02:28:00.00
       9    write
      10 next ientry 
      11 file in single-dish-reprojected.30m
      12 find
      13 table short-spacings new /resample 49 25.50 10.50 0.2000000029802322 V
      14 xy_map short-spacings
      15 header short-spacings.lmv
\end{verbatim}
\begin{description}
\item[Steps 1-10] Will ensure that the used data is in Equatorial 2000
  coordinate system (The default for \PdBI{} data) with the right
  projection center. Steps 1 and 2 opens the input and output files. Step 5
  decreases the verbosity of \class{}: This is useful when dealing with OTF
  maps with a large number of spectra. Step 4 enforces the use of the 2000
  equatorial coordinate system. Steps 5 to 10 modifies the coordinates of
  all spectra inside the input file and write them in the output files.
\item[Steps 11-13] Create the table with an on-the-fly resampling of the
  velocity axis. In the future, the \class{} \com{TABLE} will also be able
  to modify the projection center on-the-fly.
\item[Steps 14-15] Enable to verify by eye that the consistency of the
  single-dish data with the interferometric data, \ie\ the displayed header
  information for velocity axis and projection center should be identical
  to the above ones. Those steps are optional as the input really used by
  the short-spacing processing is produced at step 13.
\end{description}
It is clear that your single-dish data must be reduced before applying the
above steps. \class{} has many facilities to visualize and reduce your
data.
\end{description}

%% \section{OTF}

%% NMS's future work ;-)

%% \chapter{Self-Calibration}

%% \chapter{Imaging simulation}

%% \chapter{In and out \mapping{}}

%% \section{UV Tables (to be rewritten)}

%% {\em UV Tables} are just special {\em Tables} suited for UV data handling
%% that are created by \clic. Mapping consists of transforming these tables
%% into something more meaningful for the astronomer, either {\em Images} or
%% numbers like positions, flux densities, sizes, etc.

%% {\em UV Tables} are created by \clic\, using the {\tt TABLE} command.  The
%% {\tt TABLE } command offers several options in creating these tables. Four
%% major options should be considered:
%% \begin{enumerate}
%% \item Weighting parameters. When the calibration has been carried out
%%   correctly, the weights should include both the {\tt TSYS} correction and
%%   the amplitude {\tt CALIBRATION} factor. Then proper weights are given to
%%   every data point, so all analysis programs can estimate errors
%%   consistently.
%% \item Frequency reference for spectral line observations.  The {\tt
%%     /FREQUENCY} option should be used to compute a velocity scale relative
%%   to a given spectral line rest frequencies.
%% \item {\tt /RESAMPLE} option should be used when not all channels are
%%   required (or when the spectral resolution can be smoothed). {\tt
%%     /RESAMPLE Nc} will select only the first {\tt Nc} channels of a
%%   spectral line subband.  {\tt /RESAMPLE Nc Ref Val Res Type} offers a more
%%   general resampling.
%% \end{enumerate}

%% To summarize, a \clic{} procedure like the following is appropriate to
%% create a table:
%% \begin{verbatim}
%% SET RECEIVER 1                      ! Select receiver number
%% SET RF ON FREQUENCY ANTENNA         ! Apply RF passband calibration
%% SET AMPLITUDE RELATIVE ANTENNA      ! Apply Flux calibration
%% SET PHASE RELATIVE ANTENNA INTERNAL ! Apply Phase calibration
%% SET SELECTION LINE USB L01          ! Select the spectral line subband
%% SET WEIGHT TSYS ON                  ! Apply Tsys correction on noise
%% SET WEIGHT CAL ON                   ! Apply efficiency correction on noise
%% FIND/PROC CORR/TYPE O               ! Select Correlation data on Object.
%% ! and create the table...
%% TABLE Name NEW/FREQUENCY "SiO" 86243.45 /RESAMPLE 32
%% \end{verbatim}
%% Of course, arguments of the option depend on your particular case.  Please
%% refer to the \clic{} manual for more details. Note that the frequency is in
%% MHz.

%% \section{UVFITS}
%%
%% \section{FITS}

\chapter{Internal Helps}

\section{CLEAN Language Internal Help} \label{CLEANH}
%\input{map-help-clean}

\section{Description of Associated Tasks}
\input{mapping-task-summ}

\appendix{}

\chapter{Properties of the Fourier Transform}

The Fourier Transform of a product of two functions is the convolution of
the Fourier Transforms of the functions.

\backmatter{} %

\bibliography{map}
\bibliographystyle{aa}

\printindex{} %

\end{document}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
