NRAO Home > CASA > CASA Toolkit Reference Manual

1.1.4 imagepol - Tool

Polarimetric analysis of images
Requires: image Synopsis



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.

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 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’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(’<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----"’stokes.image’)  # Open image with Imagepol tool  
po.complexlinpol(’clp’)  # Make complex image of linear polarization disk file  
  print "Expect SEVERE error and Exception here"’clp’)         # Error  
except Exception, e:  
  print "Expected exception occurred!"  

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.

print "\t----\t Tool level Ex 3 \t----"’stokes.image’)   # Open image with Imagepol tool  
po.complexlinpol(’clp2’)  # Make complex image of linear polarization disk file  
#viewer()                 # Start viewer to give access to Complex image  

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.

Overview of Imagepol tool functions


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
fourierrotationmeasureFind 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
sigmalinpolposangError 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

    imagepol.imagepoltestimage - Function
    imagepol.complexlinpol - Function
    imagepol.complexfraclinpol - Function
    imagepol.depolratio - Function
    imagepol.close - Function
    imagepol.done - Function
    imagepol.fourierrotationmeasure - Function
    imagepol.fraclinpol - Function
    imagepol.fractotpol - Function
    imagepol.linpolint - Function
    imagepol.linpolposang - Function
    imagepol.makecomplex - Function - Function
    imagepol.pol - Function
    imagepol.rotationmeasure - Function
    imagepol.sigma - Function
    imagepol.sigmadepolratio - Function
    imagepol.sigmafraclinpol - Function
    imagepol.sigmafractotpol - Function
    imagepol.sigmalinpolint - Function
    imagepol.sigmalinpolposang - Function
    imagepol.sigmastokes - Function
    imagepol.sigmastokesi - Function
    imagepol.sigmastokesq - Function
    imagepol.sigmastokesu - Function
    imagepol.sigmastokesv - Function
    imagepol.sigmatotpolint - Function
    imagepol.stokes - Function
    imagepol.stokesi - Function
    imagepol.stokesq - Function
    imagepol.stokesu - Function
    imagepol.stokesv - Function
    imagepol.summary - Function
    imagepol.totpolint - Function

More information about CASA may be found at the CASA web page

Copyright 2016 Associated Universities Inc., Washington, D.C.

This code is available under the terms of the GNU General Public Lincense

Home | Contact Us | Directories | Site Map | Help | Privacy Policy | Search