%\section{Advanced usage, specific cases and dirty tricks}

If you end up being in any of the cases below, it is advised
to contact the authors through 
\href{mailto::imager-hotline@services.cnrs.fr}{through the hotline by E-Mail}.
The same advice holds for Polarization, although it has its
own Section (Sect.\ref{sec:polar}) .


\subsection{Really Huge Problems}
\label{sec:huge}

\imager{} basically assumes everything fits into memory. This is in general
quite fine for \NOEMA{}  data. However, for \ALMA{} data, if you are 
working with a too small computer (such as my laptop, which is 
otherwise fine), you may be lacking physical memory (RAM, Random Access Memory), 
and \imager{} may become really inefficient by using Virtual Memory instead.

To avoid time losses, \imager{} prevents reading UV data whose size
exceeds the available RAM, and warns the user if it exceeds half
of the RAM.  To treat these cases, \imager{} provides instead
a number of tools that can work sequentially on the data set,
instead of loading it in memory all at once. 

\begin{enumerate}
\item Working by subsets:\\
  the \comm{READ}{/RANGE} command allows to select an ensemble of 
  channels from a UV data. If this ensemble is small enough, \imager{} 
  can work.  At the end the \comm{WRITE}{/APPEND} and 
  \comm{WRITE}{/REPLACE} command will allow to put these channels at 
  their proper places in a deconvolved data cube.
\item Working on UV data files:\\
  Some operations on UV data, like time averaging, separation of line 
  from continuum emission, or self-calibration, and of course, spectral 
  resampling, are best done using all valid channels to avoid loosing 
  sensitivity. 
  To allow \imager{} to do them even for large data
  files, most UV-related commands have a \qom{/FILE} option which
  instructs the command to work from the corresponding data file,
  instead of the UV buffers. This includes \comm{UV\_PREVIEW}{/FILE}, 
  \comm{UV\_BASELINE}{/FILE}, \comm{UV\_FILTER}{/FILE} and especially 
  the \comm{UV\_SPLIT}{/FILE} commands. Time averaging can be performed 
  by \comm{UV\_TIME}{/FILE}, and prior sorting by time order can be
  done by \comm{UV\_SORT}{/FILE}. Spectral range extraction is possible by 
  \comm{UV\_EXTRACT}{/FILE}, spectral resampling by \comm{UV\_COMPRESS}{/FILE},
  \comm{UV\_RESAMPLE}{/FILE},  and \comm{UV\_HANNING}{/FILE}.
\end{enumerate}
By using the above commands, all operations can be done in a
quasi sequential way, avoiding to load in memory whole data sets.

Two commands have no equivalent using the \imager{} buffers, and work
only on files. Their \qom{/FILE} option is used to provide an
homogeneous syntax, but must be present for the command line
to be valid.
\begin{enumerate}
\item the \comm{UV\_MERGE}{/FILE}\\
that allows to merge together an arbitrary number of UV tables,
in spectral line (with spectral resampling) or continuum (with 
flux scaling according to a spectral index) modes.
\item the \comm{UV\_SPLIT}{/FILE}\\
that combines the capabilities of \com{UV\_BASELINE} and 
\com{UV\_FILTER} in a single command, since both operations require 
the same parameters and provide complementary informations.
\end{enumerate}

The \comm{UV\_SORT}{/FILE} command also has a different behaviour than
its memory only version \com{UV\_SORT}. While the latter creates
a transposed version of the UV table for internal use (it \textbf{cannot}
be saved), the former keeps the normal
organisation with the visibility axis first. 

An example of use of such facilities is the \qom{@}\script{~image-mosaic} script
that splits the \qom{uv\_map} step into chunks that fit in the
computer memory available to the user. 


\subsection{Moving Targets}
\label{sub:specific:moving}

The handling of moving targets is peculiar. When observed
at different dates, the pointing and phase centers need
to follow the target. This can be mistaken as a Mosaic,
although the intent is to image a single field centered
on the target. 

UVFITS handles that through the PMRA and PMDEC columns in the
AIPS\_SU tables of the UVFITS files. Documentation in
\href{https://library.nrao.edu/public/memos/aips/memos/AIPSM\_117.pdf}{Aips Memo 117}
\citet{aips117}
indicates that the unit is Degree par Day,
but experience shows that CASA writes that in Radians per Second.

To make things worse, CASA and IMAGER do not handle the 
information in the same way. On one hand, CASA reports apparent
positions at the epoch of observations (which thus differ
when the same source is observed in different configurations\footnote{
to make things worse, different proper motions can be used on
different pbserving sessions.}). On the other hand,
IMAGER refers the position to a single epoch, normally 2000.0 (although
a different reference could be used in principle), and a single set of
proper motions, ensuring consistency. 

UVFITS files can thus be mistaken as ``tiny'' mosaics.
A non-zero proper motion could indicate that we are in this 
``false'' mosaic case.

There are two ways to process such images, and both involve ignoring
the apparent mosaic. 
\begin{enumerate}
\item{Ignoring the proper motion information} Imaging can then
be done as usual using \qom{UV\_MAP} provided the apparent motion
results in position offsets below \sicvar{MOSAIC\_TOLERANCE}. The
latter can be adjusted if needed to ensure this condition is met.

To make sense, all data recovered from UVFITS have the same proper motion,
except for observations of a solar system object where the orbits
cannot be simply represented by proper motions. 

The drawback of this approach is that the epoch of the coordinates
is arbitrary: it depends on the first date found in processing.
Note that this is the approach used by CASA.

\item{Correcting for proper motions to a known epoch}. In \imager{}
one can precess back to a common epoch by using the \com{PROPER\_MOTION}
command.  The advantage is to have a clear absolute position information.

\textbf{Caution:} this should be used on UV tables that are consistent in terms
of positions. As of today (Sep-2024) this is unclear if the original
UVFITS files has observations with different proper motion information.
\end{enumerate}

\subsection{Rotating Disks: the KEPLER command}
\label{sub:specific:kepler}

A frequent analysis case in astronomy is that of rotating, flattened,
structures. A typical example is that of proto-planetary disks around
young stars, and the second category is galactic disks. 

In such circumstances, once the relation between rotation velocity and
radius is known, it is possible to recover radial profiles with 
better accuracy, by stacking spectra from a given radius after correction 
from their projected velocities. 

This is the purpose of the \com{KEPLER} command. By default, it assumes 
a Keplerian velocity profile, but the use can specify any arbitrary
(parametric) rotation curve. See \qom{HELP KEPLER} for details.

