\section{Polarization Handling}
\label{sec:polar}

\imager{} recognizes and handles polarization at different levels.
\textbf{Support for polarization is currently experimental and limited, 
but continuously improving. Contact the IMAGER authors if you need
to analyze Polarized data.}

\subsection{Data Handling}

\textbf{Importing data}\\
\indent When importing data, the \script{fits\_to\_uvt} script assumes by default
the data is unpolarized and produces the pseudo-polarisation
state "None" from the UVFITS file, by a properly weighted combination
of the two parallel hand states if more than one state is present. The
weighting is based on the relative noise in both polarization states.

Full polarization information can be preserved by adding the 
\texttt{\color{magenta} /STOKES} option to the \qom{@ fits\_to\_uvt} command. 

The \qomm{READ}{UV} command will read data with any
polarization state(s).

\vspace{0.3cm}\noindent \textbf{Processing data}\\
\indent On the contrary, practically all \imager{} commands cannot handle 
more than 1 polarization state. So far, only two commands fully support polarized
data: \com{UV\_TIME} and \com{STOKES}.

\begin{itemize}
\item \com{STOKES} is the primary command that allows to derive or extract 
a UV data with only one Stokes parameter from a UV data set with 
several polarization states. \imager{} can then process the 
individual Stokes parameters separately.
\item For convenience (because polarized data is obviously in general
bigger), the \com{UV\_TIME} command can be used for time averaging
prior to use of the \com{STOKES} command.
\item Most other commands will flatly refuse to handle data with more than 
1 polarization state (e.g. \com{UV\_FILTER}, \com{UV\_RESAMPLE}, etc\ldots).
\item For debugging purpose, some commands like \com{UV\_PREVIEW}, \com{UV\_MAP}
or \com{UV\_STAT} will operate with more than 1 polarization state,
but will not produce meaningful results (only a subset of the data
may be treated).
\end{itemize}

Some imaging strategies cannot be used on polarized data. Self-calibration
requires a different approach that is not (yet) available in \imager{}.
Also, the automatic definition of supports (\comm{MASK}{/THRESHOLD}) 
can only be done on Stokes I or parallel hand polarization states, not
on Stokes Q,U,V or cross-hand states. The same applies to spectral
line identifications.
 
\vspace{0.3cm}\noindent\textbf{Analysing data}\\
\indent Sorry, \imager{} does not yet offer integrated tools to derive e.g.
polarization fraction, or polarization vector directions. This will
come later !...  The plan is to develop a \textit{Polarization Widget} in the spirit
of the \textit{PIPELINE Widget} to streamline polarization imaging
and analysis.
 
\subsection{The STOKES command}

The \com{STOKES} command operates on the current UV buffer, or on files
if the \qom{/FILE} option is present. It allows
to extract a UV data with visibilities for one output (pseudo-)Stokes 
parameter from UV data with visibilities with 1,2 or 4 (pseudo-)Stokes
parameters. Besides the standard Stokes parameters I, Q, U, V, RR, 
LL, RL, LR (Left and Right circular), XX, YY, XY and YX (X and Y
linear) which are defined in the Sky frame,
command \com{STOKES} recognizes pseudo-Stokes values NONE, HH, VV,
HV and VH which are the linear polarization states in the frame
of the antennas (Horizontal and Vertical pure states).

Conversion from the H-V pseudo-Stokes polarization states to any standard
Stokes parameter is made by the \com{STOKES} command by applying 
the rotation due to the parallactic angle. For this, the UV data set
must contain the \texttt{PARA\_ANGLE} extra column. If it is not present,
it can be added to the data set by command \comm{UV\_ADD}{/FILE}.
That command can also insert the Doppler correction as an extra
column.

Ultimately, a similar DD, SS, DS and SD pseudo-Stokes polarization set
will be added for circular polarization. D is the first letter for
Dexter (which is the Latin name for Right), while S is the
first letter of Senester (which is the Latin name for Left).
