<casaxml xsi:schemaLocation="http://casa.nrao.edu/schema/casa.xsd file:///opt/casa/code/tools/xml/casa.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://casa.nrao.edu/schema/psetTypes.html">
<tool module="images" name="imagepol">
<shortdescription>Polarimetric analysis of images</shortdescription>
%ahkeyword registers module keywords
<keyword>polarimetry</keyword>
<include>imagepol_forward.h</include>
<include>imagepol_private.h</include> </private>
An Imagepol \tool\ provides specialized polarimetric analysis of images.
Some of these things could be done with the Lattice Expression Language
(LEL; see \htmladdnormallink{note223}{../../notes/223/223.html})
but are more conveniently offered separately.
Before it can be used, the Imagepol tool must be attached to an image
(\casa, \fits, and Miriad formats are supported) with a Stokes
coordinate axis. What you can then do with your Imagepol \tool\
depends on exactly which Stokes parameters you have in the image. You
must have some combination of Stokes I, Q, U and V on the Stokes axis.
These refer to total intensity, two components of linear polarization,
and circular polarization, respectively. Therefore, if you ask for
linear polarization and the image only has Stokes I and V, you will
The Imagepol \tool\ functions generally return, by default, an <link anchor="images:image">on-the-fly Image</link> \tool\ as their output.
In most cases, this is a ``virtual'' image. There are a range of
different sorts of ``virtual'' images in \casa\ (see <link anchor="images:image">Image</link>). But the Imagepol \toolfunctions\
generally return reference Image \tools. That is, these reference
different pieces of the original image attached to the
Imagepol \tool, either directly, or as mathematical expressions (e.g.
the polarized intensity). If you delete the attached image, you
render your Imagepol \tool\ and its outputs useless. If you wish,
rather than return a virtual image \tool, you can fill in the {\stfaf
outfile} argument of most Imagepol \tool\ functions and write the
image out to disk, associating the Image \tool\ with the disk file.
In some of the functions, the standard deviation of the thermal noise
is needed. This is for debiasing polarized intensity images or
working out statistical error images. By default it is worked out for
you from the attached image with outliers from the mean discarded.
Since it is the thermal noise it is trying to find, it is worked out
from the V, Q \& U, and finally I data in that order of
precedence. This is because Stokes V is much less likely to contain
source signal than Stokes I. You can supply the noise level if you
know it better. For example, for small images or images with few
signal-free pixels, the theoretical estimate may be better.
{\bf Analysis and Display}
Traditionally, when generating secondary and tertiary images (e.g.
position angle, fractional polarization, rotation measure etc), one
masks the output image according to some statistical test. For example,
if the error in the output image is greater than some value, or the
errors in the input images are greater than some value. Imagepol
\tools\ do not offer this kind of masking. It does provide you with the
error images for the derived images. By using LEL when you analyze your
images, you can mask the images however you want when you use them.
That is, we defer the error interpretation as long as possible. Here is
print "\t----\t Tool level Ex 1 \t----"
potool = casac.homefinder.find_home_by_name('imagepolHome')
po.imagepoltestimage(outfile='stokes.image') # Create test image
po.close() # Close so we can illustrate opening an image