imagepol - Tool

An Imagepol tool provides specialized polarimetric analysis of images. Some of these things could be done with the Lattice Expression Language (LEL; see note223) 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 get an error.

The Imagepol tool functions generally return, by default, an on-the-fly Image 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 Image). But the Imagepol tool functions 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 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.

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 an example.

"""
#
print "\t----\t Tool level Ex 1 \t----"
potool = casac.homefinder.find_home_by_name(’imagepolHome’)
po = potool.create()
po.imagepoltestimage(outfile=’stokes.image’)  # Create test image
po.close()                      # Close so we can illustrate opening an image
po.open(’stokes.image’)         # Open image with Imagepol tool
lpa = po.linpolposang()         # Linearly polarized position angle image
lpaerr = po.sigmalinpolposang() # Error in linearly polarized position angle image
lpa.statistics();               # Get statistics on position angle image
#viewer(mask=lpaerr.name()+’<5’)  # Display when p.a. error < 5 degrees
#
"""

Display is handled via the Viewer tool. It can display and overlay combinations of raster, contour and vector representations of your data.

It is common to display linear polarization data via vectors where the position angle of the vector is the position angle of the linear polarized radiation, and the amplitude of the vector is proportional to either the total polarized intensity or fractional polarized intensity.

The data source of a vector display is either a Complex or a Float image. If it is a Complex image (e.g. the complex linear polarization Q + iU) then both the amplitude and the phase (position angle) are available. If it is just a Float image, then it is assumed to be the position angle and an amplitude of unity will be provided. The angular units are given by image brightness units which you can set with function setbrightnessunits. If the units are not recognized as angular, degrees are assumed.

The position angle is measured positive North through East when you display a plane holding a celestial coordinate (the usual astronomical convention). For other axis/coordinate combinations, a positive position angle is measured from +x to +y in the absolute world coordinate frame.

The Imagepol tool can create Complex disk images for you via functions complexlinpol (complex linear polarization), complexfraclinpol (complex fractional linear polarization) and makecomplex (takes amp/phase or real/imag). As well as these Complex images, you can also make Float images of the linearly polarized intensity, linearly polarized position angle, and the fractional linearly polarized intensity (see below).

Now, the Image tool cannot yet deal with Complex images (it will in the future). This means that you cannot currently do

"""
#
print "\t----\t Tool level Ex 2 \t----"
po.open(’stokes.image’)  # Open image with Imagepol tool
po.complexlinpol(’clp’)  # Make complex image of linear polarization disk file
try:
  print "Expect SEVERE error and Exception here"
  ia.open(’clp’)         # Error
except Exception, e:
  print "Expected exception occurred!"
po.close()
#
"""

which is a bit annoying presently. However, the Viewer tool is able to read Complex images so that you are able to display them ok.

If you wanted to make a vector map display you would select the appropriate image in the Viewer’s data manager GUI, click ’Vector Map’ on the right hand side and it would appear in the display. Note that the Viewer’s Vector map display capability also offers you amplitude noise debiasing and the On-The-Fly mask.

imagepoltestimage	Attach the Imagepol tool to a test image file
complexlinpol	Complex linear polarization
complexfraclinpol	Complex fractional linear polarization
depolratio	Linear depolarization ratio
close	Close the image tool
done	Close this Imagepol tool
fourierrotationmeasure	Find Rotation Measure (Fourier approach)
fraclinpol	Fractional linear polarization
fractotpol	Fractional total polarization
linpolint	Linearly polarized intensity
linpolposang	Linearly polarized position angle
makecomplex	Make a Complex image
open	Open a new image with this imagepol tool
pol	Polarized quantities
rotationmeasure	Find Rotation Measure (traditional approach)
sigma	Find best guess at thermal noise
sigmadepolratio	Error in linear depolarization ratio
sigmafraclinpol	Error in fractional linear polarization
sigmafractotpol	Error in fractional total polarization
sigmalinpolint	Error in linearly polarized intensity

sigmalinpolposang	Error in linearly polarized position angle
sigmastokes	Find standard deviation of specified Stokes data
sigmastokesi	Find standard deviation of Stokes I data
sigmastokesq	Find standard deviation of Stokes Q data
sigmastokesu	Find standard deviation of Stokes U data
sigmastokesv	Find standard deviation of Stokes V data
sigmatotpolint	Error in total polarized intensity
stokes	Stokes
stokesi	Stokes I
stokesq	Stokes Q
stokesu	Stokes U
stokesv	Stokes V
summary	Summarise Imagepol tool
totpolint	Total polarized intensity

Display is handled via the Viewer tool. It can display and overlay combinations of raster, contour and vector representations of your data.

Now, the Image tool cannot yet deal with Complex images (it will in the future). This means that you cannot currently do

which is a bit annoying presently. However, the Viewer tool is able to read Complex images so that you are able to display them ok.

1.1.4 imagepol - Tool