imagepol - Tool

NRAO Home > CASA > CASA Toolkit Reference Manual

1.1.4 imagepol - Tool

Polarimetric analysis of images
Requires: image Synopsis

Description

Summary

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.

General

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

"""
#
print "\t----\t Tool level Ex 3 \t----"
po.open(’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

Access to the different Stokes subimages is via functions stokes, stokesi, stokesq, stokesu, and stokesv.
Create the standard secondary and tertiary polarization images with
- complexfraclinpol - complex fractional linear polarization
- complexlinpol - complex linear polarization
- makecomplex - make complex image from amp/phase or real/imag
- pol - polarized quantities as specified
- linpolint - linearly polarized intensity
- linpolposang - linearly polarized position angle
- totpolint - total polarized intensity
- fraclinpol - fractional linear polarization
- fractotpol - fractional total polarization
- depolratio - linear depolarization ratio
Create the standard secondary and tertiary polarization error images (simple propagation of Gaussian errors) with
- sigma - best guess at thermal noise
- sigmastokes - specified Stokes parameter
- sigmastokesi - Stokes I
- sigmastokesq - Stokes Q
- sigmastokesu - Stokes U
- sigmastokesv - Stokes V
- sigmalinpolint - linearly polarized intensity
- sigmalinpolposang - linearly polarized position angle
- sigmatotpolint - total polarized intensity
- sigmafraclinpol - fractional linear polarization
- sigmafractotpol - fractional total polarization
- sigmadepolratio - linear depolarization ratio
You can compute Rotation Measure images via either the traditional techniques involving a number of different frequencies (regularly or irregularly spaced) with function rotationmeasure or via a new Fourier Technique for many regularly-spaced frequencies with function fourierrotationmeasure.

Methods

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

[next] [prev] [prev-tail] [front] [up]

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

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