Displaying the Results

Linear polarimetry results are usually expressed in terms of the percentage polarization and the orientation of the plane of polarization. Vectors may be used to represent these quantities graphically. The following POLPACK applications can be used to produce a map of vectors describing the polarization at different points on the sky:

POLVEC

- This converts a 3 or 4D NDF containing Stokes parameters (such as produced by POLKA or POLCAL) into a catalogue of polarization vectors containing the following columns:

X

- X pixel co-ordinates within the supplied cube.

Y

- Y pixel co-ordinates within the supplied cube.

Z

- Z pixel co-ordinates within the supplied cube (only produced for spectropolarimetry data).

I

- Total intensity.

Q

- Stokes parameter Q.

U

- Stokes parameter U.

P

- Percentage polarization.

ANG

- The anti-clockwise angle from the reference direction to the plane of polarization, in degrees.

For circular polarimetry, the Q and U columns are replaced by a single V column. If variance information is available (see here) then columns are also produced holding the standard deviations associated with each of the above quantities (except X, Y and Z). Each pixel in the x-y plane of the supplied cube produces one or more rows in the catalogue, the number being equal to the number of spectral channels in the data. So for single waveband polarimetry, the catalogue will contain one row for each pixel in the x-y plane, but for spectropolarimetry data with (say) 100 spectral channels, there will be 100 rows for each pixel in the x-y plane. The reference direction for the $Q$, $U$ and $ANG$ columns is chosen in the same way as when producing the Stokes vectors (i.e. north, if WCS information is available to define north, or the second image axis otherwise).

POLVEC can also produce a set of 2 or 3D NDFS holding the above quantities.

POLBIN

- This accepts a catalogue containing Stokes parameters as input (such as produced by POLVEC), and creates a new output catalogue in the same format, but containing fewer rows (i.e. fewer polarization vectors). The output catalogue is formed by binning the Stokes vectors in the input catalogue within a grid of equally sized rectangular bins. Corresponding values for the P and ANG columns are calculated on the basis of the binned Stokes parameters. Spectropolarimetry data can be binned independently in the spatial and spectral axes.

POLPLOT

- This displays a map of polarization vectors in a single spectral channel, obtained from a catalogue produced by POLVEC or POLBIN (the catalogue must contain more than a single spatial position). If the data contains more than one spectral channel, the specific spectral channel to display can be selected. If the map is drawn over an existing picture, then the vectors can be aligned with the previously displayed picture.

In addition, the catalogues produced by POLBIN and POLVEC can be examined and interactively edited using the polarimetry toolbox within GAIA .

Since the polarization parameters are stored in a catalogue, the CURSA package can be used to examine and manipulate them. One particularly useful facility within CURSA is the CATSELECT application, which allows rows within a catalogue to be selected on the basis of an arbitrary mathematical expression. For instance the following commands create a new catalogue called selcat.FIT which contains all the vectors from bincat.FIT for which the polarization is less than 30% and has a standard deviation less than 5%:

   % cursa
   % catselect catin=bincat catout=selcat norejcat seltyp=e "expr='p<30 & dp<5'"

The XCATVIEW application allows you to examine the data in a catalogue, using a Graphical User Interface to control the operation and display the results.

Note, the POLIMAGE application can be used to extract the values from a specified column of a catalogue into an image. The image can be either a simple 1-dimensional list of the column values, or it can be a 2-dimensional image in which the spatial position of each value is retained. In this case, the image is formed by binning the column values into a grid of pixels.

A typical recipe for using the above applications (together with KAPPA) to display a spatial vector map would involve the following steps:

1. Convert the 3D NDF in file cube.sdf containing Stokes vectors (created by POLKA) into a catalogue stored in file cat.FIT:

      % polvec cube cat
   

2. Bin the catalogue to reduce the noise and decrease the density of vectors in the final map. The bins used in this example are 8 by 8 pixels (measured in the x-y plane of the Stokes parameter NDF cube.sdf), and the Stokes parameters are combined using a median. The binned catalogue is stored in file bincat.FIT:

      % polbin cat bincat 8 method=med
   

3. Create a new catalogue (in file selcat.FIT) containing just the vectors with polarizations of less than 50% and standard deviations of less than 5%:

      % cursa
      % catselect catin=bincat catout=selcat norejcat seltyp=e "expr='p<50 & dp<5'"
   

4. Start up KAPPA, and then select the graphics device and the image display device (both are set to an X windows display in this example):

      % kappa
      % gdset xwindows
      % idset xwindows
   

5. Clear the screen:

      % gdclear
   

6. Create a ``picture'' to contain a grey-scale display of the total intensity. A picture is an area of the screen in which subsequent graphics will appear. The one we create here is centred on the screen and occupies three quarters of its height and width. This leaves a border available for annotation round the display:

      % picdef mode=cc fraction=0.75
   

7. Display the total intensity image contained in the bottom plane of the Stokes vector cube, and ensure it is displayed with the standard monochrome colour table:

      % display "cube(,,1)" mode=per percentiles="[5,95]"
      % lutgrey
   

8. Re-select the ``base picture''. This is a picture which corresponds to the whole screen. We need to do this because output from graphics applications such as POLPLOT is usually restricted to the current picture. At the moment, the current picture is the one created by PICDEF above which contains the grey-scale image. We want the key produced by POLPLOT to appear outside this picture. We therefore need to select the base picture so that POLPLOT has room for the key within the current picture:

      % piclist picnum=1
   

9. Display the vector map, retaining the existing picture so that the vectors appear in alignment with the previously displayed total intensity image. The vectors are drawn in blue. A default scale will be used for the vectors, but this can be over-ridden if necessary by specifying a value for parameter VSCALE:

      % polplot selcat noclear "style='colour(vect)=blue'"
   

The above basic recipe can be modified in many ways. For instance:

• If you want to display only a sub-section of the map, specify the sub-section in step by including bounds for the first and second axes of input cube. For instance, to restrict the display to X pixel co-ordinates 50 to 100, and Y pixel co-ordinates 300 to 380, do:

     % display "cube(50:100,300:380,1)" mode=per percentiles="[5,95]"
  

• If you do not want the vectors to be overlaid on a total intensity image, then omit steps and , and remove the noclear setting from the POLPLOT command line in step .

• If you want the vectors overlaid on a contour map instead of a grey-scale image, replace step with:

     % contour "cube(,,1)" mode=per percentiles="[90,93,96,99]" noaxes nokey
  

• If you want your output in the form of a PostScript file, there is an extra step. This is because graphics applications such as DISPLAY, CONTOUR, POLPLOT, etc., produce separate output PostScript files which then need to be combined into a single file using the psmerge command. In step , specify the device as epsf_l (Encapsulated PostScript, landscape mode) instead of xwindows. The first graphics applications to be run will then write its output to the file gks74.ps, and subsequent graphics applications will write their output to files gks74.ps.1, gks74.ps.2, etc.⁹. To produce a contour map with overlaid vectors, replace steps and with:

     % rm gks74.ps*
     % contour "cube(,,1)" mode=per percentiles="[90,93,96,99]" noaxes nokey
     % mv gks74.ps.1 contour.ps
     % polplot selcat noclear 
     % mv gks74.ps.1 polplot.ps
     % psmerge polplot.ps contour.ps > total.ps
  

  Note, CONTOUR produces two PostScript files (gks74.ps and gks74.ps.1). Make sure you use gks74.ps.1¹⁰.

  The file total.ps then contains the combined PostScript data which can be printed on a suitable printer.

These are just a few examples of the possibilities for varying the above recipe. Familiarity with the parameters of the relevant KAPPA and POLPACK applications will suggest many more.