Creation of Stokes Parameters

The creation of Stokes vectors from the calibrated, imported target exposures involves the following steps:

• The extraction of the $O$ and $E$ ray images in each target exposure into separate files (dual-beam data only).
• The alignment of all images, so that a given pixel position corresponds to the same place on the sky in all images.
• The subtraction of a sky background from each image.
• The calculation of the Stokes vectors from these sky-subtracted images.

The first three of these steps can be performed using applications from KAPPA and CCDPACK, and the final step is performed by the POLPACK application POLCAL. However, this is a fairly involved process since the available applications are somewhat low-level. For this reason, POLPACK includes a tool called POLKA which simplifies the process. POLKA is effectively a script which calls the KAPPA, CCDPACK and POLPACK applications required to perform all four of the steps listed above⁷. While some options are provided to allow the user to customise the exact recipe used, POLKA does not provide as much versatility or control over the processing as would be available if the individual applications were called ``by hand''. If you hit a problem which POLKA cannot handle, then you may need to adopt this alternative approach.

One specific restriction on POLKA is that it can only be used with 2-dimensional intensity images (i.e. not 3-dimensional spectropolarimetry data). To create Stokes vectors from 3-dimensional intensity cubes, the cubes must first be aligned in both the spatial and the spectral domain (e.g. using CCDPACK and KAPPA applications ``by hand''), and then POLCAL should be used to create a 4-dimensional hyper cube containing Stokes vectors.

POLKA requires you to identify the following features within the supplied images:

• The areas containing the $O$ and $E$ ray images (dual-beam data only).
• The sky areas.
• Any star-like features which can be used to align the images.

A Graphical User Interface (GUI) is created for this purpose, including an image display area in which any of the input images may be displayed, and controls to select any of the above features (see Figure  ). Note, if you find the image display area uncomfortably small, it can be made larger by assigning a suitable value to the DPI parameter when POLKA is started. Once the required features have been supplied, POLKA commences the processing of the supplied data frames. This may take a significant length of time depending on your hardware, and the size and number of your images. A window displays the progress being made during this phase.

The Graphical User Interface presented by POLKA.

Once complete, a 3D cube is created in which the x-y plane corresponds to pixel positions within the extracted, aligned intensity images. Each plane in the cube contains a single Stokes parameter. The lowest plane is always the total intensity. The other planes contain either Q and U for linear polarization, or V for circular polarization⁸. In addition, the separate aligned, sky-subtracted intensity images on which the Stokes parameters were based may be saved once the processing is complete.

The reference direction (see this section) for the Stokes vectors in the output cube will not in general be the same as the reference direction in the input intensity images. The output reference direction is chosen as follows:

• If the input data has World Co-ordinate System (WCS) information which describes a celestial co-ordinate system such as RA/DEC, galactic longitude/latitude, etc., then the reference direction in the output cube will be north within the same celestial co-ordinate system. Instructions on setting up such WCS information is available here.

• If the input data does not contain WCS information for a celestial co-ordinate system, then the reference direction will be the second pixel axis within the image (i.e. ``Y'', or ``upwards'' if the image is displayed normally).

The POLKA application has many parameters. The values used for some of these may be changed from within the GUI. However, some may not be changed and should be assigned appropriate values when invoking POLKA. Of these, the most important will usually be:

IN

- A list of the input target frames. These should have been calibrated and imported. The list may be supplied in several forms (described here).

MODE

- Indicates what sort of polarization you are measuring. It can be ``CIRCULAR'' or ``LINEAR''.

OUT

- If you have single-beam, or non-polarimetric data, this parameter is used to obtain a list of the output images to receive the aligned, sky-subtracted images. If a null value (!) is supplied, these images are not saved. For dual-beam data, parameters OUT_E and OUT_O are used instead.

OUT_E

- A list of the output images to receive the extracted, aligned, sky-subtracted $E$ ray images. If a null value (!) is supplied, these images are not saved. Only used in dual-beam mode.

OUT_O

- This is like OUT_E, but refers to the $O$ ray images instead of the $E$ ray images. Only used in dual-beam mode.

OUT_S

- The name of the output cube to receive the Stokes parameters. If a null value (!) is supplied, no Stokes parameters are created.

POL

- This should be set to FALSE if you want to use POLKA as a general purpose image alignment tool for non-polarimetric data. If this is done, the aligned, sky-subtracted images should be specified using parameter OUT (parameters OUT_S, OUT_E and OUT_O are then not used). In this mode, the supplied images are treated like $O$ ray images, and the controls related to the $E$ ray images are disabled.

SKYFRAMES

- POLKA provides two methods of sky subtraction. If a list of frames is supplied for parameter SKYFRAMES, then these frames are subtracted pixel-by-pixel from the target intensity frames. If a null parameter value (!) is supplied for SKYFRAMES, then you must use the GUI to identify areas of sky within each of the input target frames. A smooth surface is then fitted to these areas and used as the sky background.

A separate guide is available describing POLKA in detail. It contains a step-by-step tutorial, detailed descriptions of each control in the GUI, answers to some common questions, etc. It may be accessed using the Help menu within the GUI. When POLKA is activated, the tutorial is automatically displayed in a WWW browser (this may be disabled using the STARTHELP parameter when running POLKA). If you are new to POLKA, it is a good idea to work your way through the tutorial first.