imagepol - Tool

Postscript file available

Polarimetric analysis of images

include "imagepol.g"

Constructors

imagepol	Create an Imagepol tool from an AIPS++ image file
imagepoltestimage	Create an Imagepol tool and a test image file

Functions

complexfraclinpol	Complex fractional linear polarization
complexlinpol	Complex linear polarization
depolratio	Linear depolarization ratio
done	Destroy this Imagepol tool
fourierrotationmeasure	Find Rotation Measure (Fourier approach)
fraclinpol	Fractional linear polarization
fractotpol	Fractional total polarization
id	Return the fundamental identifier of this tool
linpolint	Linearly polarized intensity
linpolposang	Linearly polarized position angle
makecomplex	Make a Complex image
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

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

You construct an Imagepol tool from an image (AIPS++, FITS, and Miriad formats are supported) with a Stokes coordinate axis. What you can 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 Image tool as their output. In most cases, this is a ``virtual'' image. There are a range of different sorts of ``virtual'' images in AIPS++ (see Image). But the Imagepol tool functions generally return reference Image tools. That is, these reference different pieces of the original image that was used to construct the Imagepol tool, either directly, or as mathematical expressions (e.g. the polarized intensity). If you delete the construction 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 construction 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 putput 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.

Example

include 'imagepol.g'
ip := imagepol('stokes.image')       # Construct Imagepol tool from image
lpa := ip.linpolposang()             # Linearly polarized position angle image
lpaerr := ip.sigmalinpolposang()     # Error in linearly polarized position angle image
lpa.view(mask='$lpaerr<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. Please see the view function of the Image tool and the document Getting Results) for high-level information on how to display images in general.

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

include 'imagepol.g'
p := imagepol('iquv.im')  # Make Imagepol tool
p.complexlinpol('clp')    # Make complex image of linear polarization disk file 
clp := image('clp')       # Error

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.

include 'imagepol.g'
include 'viewer.g'
p := imagepol('iquv.im')  # Make Imagepol tool
p.complexlinpol('clp')    # Make complex image of linear polarization disk file 
dv.gui()                  # Start data manager 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.

Next: imagepol - Constructor Up: images - Module Previous: imageprofilefitter.type - Function Contents Index

	Package	general
	Module	images