5 Data Reduction Using POLPACK

This section gives a detailed description of the steps involved in using POLPACK to produce a vector map from single-beam or dual-beam polarimetry or spectropolarimetry data. It is assumed that the data conforms to the model outlined in one of the two previous sections. An over-view of the data reduction process is given in Figure 6.

Figure 6: The main steps in the production of a polarization map.

All POLPACK applications use standard Starlink subroutine libraries for accessing parameters, producing graphics, reporting errors, etc. They therefore look and feel very similar to applications in other Starlink packages such as KAPPA and CCDPACK. The following sections in SUN/95 (the KAPPA manual) should therefore be consulted for general information about these issues:

• “Parameters”
• “Graphics Devices and Files”
• “Plotting Styles and Attributes”
• “Data Structures”
• “NDF Sections”
• “NDF History”
• “The Graphics Database”
• “Using World Co-ordinate Systems”

5.1 Format Conversion

The first step is to ensure that your data files are in a format which POLPACK can process. The native data format used by POLPACK is the Starlink NDF format (note, NDF structures are usually stored in files with a file type of .sdf). If your data is already in this format, then you can proceed immediately to the next step. Otherwise, you have two options:

(1)

You can convert your data files into NDF format explicitly at the beginning, and use the NDF versions there-after. The CONVERT package (see SUN/55) provides facilities for converting to and from most common astronomical data formats. For instance, if your data is in the form of a set of FITS files, you could use commands similar to the following to convert them into NDFs:

  % convert
  % fits2ndf "*.fit" "*"

Note that the % represents the C-shell prompt and should not be typed. The first command initialises the commands required to use the CONVERT package. The second command converts all FITS files with a file type of .fit within the current directory, into equivalent NDFs with the same file names, but a file type of .sdf⁴. The .sdf files can then be given as inputs to any application from POLPACK, CCDPACK or KAPPA.

(2)

Alternatively, you can rely on the facilities of the NDF library to perform automatic on-the-fly data conversions as and when necessary. Using this technique, POLPACK, CCDPACK and KAPPA all appear to process your data files directly without you needing to do any explicit data conversion. All you need to do to enable these facilities is to initialise the CONVERT package using the single command:

  % convert

If you adopt this approach, you may still see references to “NDFs” appearing on the screen. There is usually no significance in the use of the term “NDF” in this context (unless there are indications to the contrary), and you should understand these as referring to your own non-NDF data files.

For spectropolarimetry data, the spectral channel must vary along pixel axis 3, and pixel axes 1 and 2 must be spatial axes. The KAPPA application PERMAXES can be used to rearrange axes into the required order. If your data is one dimensional (i.e. has no spatial coverage) then you can use PERMAXES as follows to add two spatial axes each covering a single pixel:

where data-1d.sdf is the 1-dimensional input file, and data-3d.sdf is the 3-dimensional output file. The section specifier “(,1,1)” indicates that data-1d should be treated as if it had 2 extra trailing axes each spanning a single pixel. PERMAXES then rearranges the axes so that the spectral axis (previously axis 1) becomes the last axis (axis 3). Of course, since there is no spatial coverage, you will not be able to display such data using POLPLOT (use POLIMAGE and KAPPA LINPLOT instead).

5.2 Corrections for Instrumental Effects

POLPACK expects your data to be calibrated so that the pixel values are proportional to the analysed intensity. You should therefore correct your data for any known instrumental effects such as non-linearity, variation of sensitivity across the detector, zero point offsets, etc., before proceeding to use POLPACK. The details will obviously depend on your detector, but if you are using a CCD camera, then the CCDPACK package (see SUN/139) will usually be able to perform these corrections.

If you are using dual-beam data, and target exposures are available at half-wave plate positions of 45.0°  and 67.5°  (as well as 0°  and 22.5° ), then POLPACK can make corrections for the following effects when calculating the Stokes vectors:

(1)

Differences in exposure times between the target exposures

(2)

A constant difference in sensitivity between the $O$ and $E$ ray channels.

These effects therefore do not need to be calibrated out of the raw data.

One aspect of calibration common to most detectors is flat-fielding. If your flat-fields are obtained in polarized light (such as produced by reflection or scattering, for instance), then the mean signals measured in the $O$ and $E$ ray images of dual-beam data will be different. When such a flat-field is used to calibrate your target exposures, these different mean levels will introduce an apparent difference in sensitivity between the $O$ and $E$ ray channels. If the same flat-field is used for all target exposures, then this difference in sensitivity will be constant and can be removed while calculating the Stokes parameters (provided you have target exposures at half-wave plate positions of 0, 22.5, 45 and 67.5 degrees). Appendix C contains a mathematical description of the flat-fielding process for dual-beam data, and the corrections applied by POLPACK when calculating the Stokes parameters.

Whether you are using dual-beam or single-beam data, do not forget to use the same flat-field to correct all target exposures. This will usually be a master flat-field formed by co-adding several individual flat-field exposures. This reduces the noise in the master flat-field. This is important for two reasons:

(1)

Any noise in the flat-field gets passed directly into the final results.

(2)

Any noise in the flat-field appears in each of the flat-fielded intensity images, resulting in a degree of correlation between the noise in these images. This can cause any variance estimates for the final polarization parameters (see next paragraph) to be wrong. This is because the variance calculations assume that there is no correlation between the noise in different images.

Another aspect of instrumental calibration is the estimation of the uncertainty on every pixel value. If you know the noise characteristics of your detector, you may be able to store this information with your data in the form of an NDF VARIANCE component. This is an array holding an estimate of the variance at every pixel in your data. If present, POLPACK will process this information to obtain estimates of the uncertainty in the final polarization parameters. If you use CCDPACK to calibrate your data, then the DEBIAS application can be used to create a VARIANCE component.

If you are using single-beam data, there is an option to estimate the variances associated with the input data while calculating the Stokes vectors. This enables variances to be found for the Stokes vectors even if your input data has no usable variance information. See section E for details.

5.3 Starting up POLPACK

The applications within POLPACK are made available from the C shell using the command:

This command must be issued before attempting to use any POLPACK applications.

5.4 Importing Header Information

POLPACK needs to know certain items of header information about each of the supplied data files. These include the half-wave plate position, the orientation of the reference direction, etc. Different instruments may store this information in different ways, and for this reason, POLPACK includes an application which finds the required items of information and stores them away in a standard place within the data file from where the other POLPACK applications can extract them when needed. This standard place is known as the “POLPACK extension”. The process of copying this information from its original, instrument specific location, into the POLPACK extension is known as “importing” the data, and is performed by the POLIMP application⁵, or the POLEXT application (if you have no FITS headers available).

You tell POLIMP where to find each required item of information by supplying it with a “control table”. This is a text file containing a line for each item of information to be imported into the POLPACK extension. Each such item has a name by which other POLPACK applications refer to it (these are described in appendix F). As well as the name of a POLPACK extension item, each line of the control table should contain a description of where to obtained the corresponding value. This description is given in terms of FITS keywords. For instance, the line

tells POLIMP to find the value of the FITS keyword HWPANG and store it as item “WPLATE” in the POLPACK extension (this is the half-wave plate position angle).

If your data are supplied in the form of a set of FITS files, then the HWPANG value would simply be obtained from the primary header. If your data is supplied in the form of a set of NDF structures, then the value would be read from the FITS extension in the NDF structure (which should have been created by the data acquisition system). For other data formats, the origin of the keyword value depends on how the data conversion is performed. SUN/55 contains details of how FITS keywords are created from foreign data files.

The POLIMP control table also allows POLPACK extension items to be derived from one or more FITS keyword values, combined together to form a Fortran-like mathematical expression. For instance, this may be useful if the FITS keyword uses a different set of units, or has a different sign convention. When used in this way, each FITS keyword must be “declared” earlier in the control table. This declaration tells POLIMP what sort of data values the keyword can take. For instance:

converts the value of the FITS keyword ROTA from radians to degrees, and assigns the result to the item ANGROT. The first line informs POLIMP that the keyword ROTA should be treated as a single precision floating point value. The recognized data types are:

See the description of the POLIMP application for further details of the syntax of the control table.

There is also a POLEXP application which reverses the importing process. It copies the information stored in the POLPACK extension into named FITS keywords. The primary purpose of POLEXP is to allow the automatic format conversion facilities of the NDF library to convert a POLPACK NDF structure back into a foreign data file. It is generally not necessary for users to call POLEXP explicitly.

The POLEXT application allows the contents of the POLPACK extension to be set to explicit values supplied by the user. This can be useful if your data does not contain any FITS headers. POLEXT will also list the contents of the POLPACK extension. If your data is stored in NDF format, you can also use the hdstrace command to list the contents of the NDF extension. For instance, to check the contents of the POLPACK extension in the NDF partproc.sdf, do:

5.5 Reference Directions

The reference direction within each image is recorded by adding a new co-ordinate Frame to the World Co-ordinate System (WCS) information stored with the image (see section 5.9). The new Frame has the Domain name POLANAL, and its first axis is parallel to the reference direction. This Frame will be updated by any POLPACK application which produces a change in the orientation of the reference direction. This will happen for instance if POLKA introduces a rotation into the images during the alignment process⁶. If you process your images using applications from another package, then be aware that the POLANAL Frame may be lost or invalidated. Basically, you will probably be safe if you only use packages which correctly propagate WCS information in form of Starlink AST FrameSets (see SUN/210). KAPPA, for instance, is such a package.

You specify the reference direction when you run POLIMP or POLEXT by giving a value for the ANGROT item (the anti-clockwise angle in degrees from the first image axis to the reference direction). In versions of POLPACK prior to V2.0, ANGROT was stored explicitly as a floating point value within the POLPACK extension. As of V2.0, ANGROT is no longer stored in the POLPACK extension. Instead, its value is implied by the orientation of the POLANAL Frame within the WCS information. However, you can consider this an “implementation detail” – as far as the general user is concerned, ANGROT can be treated like any of the genuine extension items. In particular, it can be set or examined using POLIMP, POLEXT and POLEXP just like any other POLPACK header item.

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

Figure 7: 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 section 3.1) 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 in section 5.9.
• 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:

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.

5.7 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:

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

Since the polarization parameters are stored in a catalogue, TOPCAT (see http://www.starlink.ac.uk/topcat/) can be used to examine them. Also, the STILTS package (http://www.starlink.ac.uk/stilts/) can be used to manipulate them. 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%:

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%:

  % stilts tpipe in=bincat.FIT out=selcat.FIT cmd=’select "p<50 && dp<5"’

(4)

Re-instate the WCS (stilts does not copy the POLPACK WCS information from input to output):

  % polwcscopy in=selcat ref=bincat out=selcat2

(5)

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

  % kappa
  % gdset xwindows

(6)

Clear the screen:

  % gdclear

(7)

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

(8)

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

(9)

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

(10)

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 selcat2 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 (8) 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 (7) and (8), and remove the noclear setting from the POLPLOT command line in step (10).
• If you want the vectors overlaid on a contour map instead of a grey-scale image, replace step (8) 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, you should choose one of the “accumulating” postscript devices such as “/acps, from the list of graphics devices produced by the KAPPA GDNAMES command. This causes the postscript output from each subsequent command to be accumulated into a single postscript file, which by default is called pgplot.ps. For instance, to produce a contour map with overlaid vectors, do:
    % setenv PGPLOT_PS_FONT Times
    % gdset \acps
    % gdclear
    % contour "cube(,,1)" mode=per percentiles="[90,93,96,99]" noaxes nokey
    % polplot selcat2 noclear

  The file pgplot.ps then contains the combined PostScript data from both the contour plot and the vector plot, which can be converted to some other graphics format or printed on a suitable printer

  Note setting environment variable PGPLOT_PS_FONT to “Times” causes text to be produced using a higher quality postscript font (Times New Roman). Other alternative font names are “Helvetica”, “Courier”, “NewCentury” and “Zapf”. Leaving the environment variable unset will cause the lower quality default PGPLOT font to be used.

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.

5.7.1 Displaying Spectropolarimetry Data

The techniques used in the examples in the previous section can also be used to display a single spectral channel when using spectropolarimetry data, but only if the data has some spatial coverage (i.e. has more than 1 pixel in the x-y plane). To do this, specify the spectral channel to be displayed by POLPLOT, using parameter ZAXVAL or ZCOLVAL. These two parameters specify the spectral channel in different ways:

• ZCOLVAL requires the spectral channel to be given as a value for the Z column in the catalogue. This column usually holds floating point pixel coordinates which describe a position on the third pixel axis of the original intensity NDFs. These will usually have a fractional part of 0.5, indicating that the position refers to the centre of a pixel.
• ZAXVAL requires the spectral channel to be given as a value for the third axis in the current Frame of the WCS component of the original intensity NDFs. If the spectral axis has been calibrated, this axis may specify the spectral channel in some physical units such as Hertz, Angstroms, nanometres, microns, km/s, etc. If the spectral channel has not been calibrated, then ZAXVAL will usually require a value in pixel coordinates to be supplied (just like ZCOLVAL). The units required by ZAXVAL can be determined by entering a colon (“:”) when prompted for ZAXVAL. This will produce a description of the current coordinate Frame (you should supply a value for axis 3). The details of the description depend on the nature of the WCS calibration supplied in the original NDFs (which is outside the control of POLPACK).

If a ZAXVAL value is supplied, it is converted into the corresponding ZCOLVAL value. Either way, only vectors for which the Z column value in the catalogue equals the specified ZCOLVAL value are plotted. If the catalogue contains no vectors with the specified ZCOLVAL, then the nearest ZCOLVAL for which some vectors are available is used instead of the supplied ZCOLVAL. The value actually used is reported to the user and included in the default title for the plot.

An alternative method for displaying spectropolarimetry data is to use KAPPA LINPLOT to display line plots of the quantities of interest, as a function of spectral channel. This method has the advantage that, unlike POLPLOT, it can be used even if your data has no spatial coverage (i.e. covers only a single pixel in the x-y plane). Before using LINPLOT you need to create an NDF containing the data to be plotted. To do this, use POLIMAGE. As an example, to plot polarization against wavelength at ( x=1.5, y=2.5 ) for the data in catalogue mycat.FIT, do:

POLIMAGE creates the file pdata.sdf which is a 3D NDF containing the values from the “P” column in mycat.FIT. The VARIANCE component of the NDF is filled with the square of the values in the “DP” column (do not supply a value for parameter COLVAR if the catalogue does not contain a suitable error column). The values assigned to the BOX parameter should usually be the same as the bin sizes used to create the catalogue (use 1,1,1 if the catalogue has not been binned). The LINPLOT command then plots the NDF data values at X and Y pixel indices of 2 and 3 (i.e. pixel coordinates ( 1.5, 2.5 ) ), and covering the entire third (Z) axis. If the catalogue contains data only for a single x-y position, then the LINPLOT parameter NDF could be assigned the value “pdata” (without any section specified) since there is no ambiguity about which x-y pixel to use. The ERRBAR parameter indicates that error bars are to be plotted (this would not be possible if we had not assigned a value to the COLVAR parameter when running POLIMAGE).

There are many other options for using these applications. See there reference documentation for details.

5.8 Getting Help

Information describing all POLPACK commands is available in several forms:

• As simple text in the command-line window. Type:
    % polhelp

  Additional arguments may be given indicating the subject on which help is required. For instance:

    % polhelp polka parameters

  will enter the help library at the point containing information on the parameters available for application POLKA.

• As hypertext in a separate browser window. Type:
    % showme sun223
• In response to prompts issued by applications for parameter values. Entering a single question mark will display help on the parameter being prompted for, and then return you to the parameter prompt. Entering two question marks also displays help on the parameter, but will leave you in the help library, allowing you to navigate through any other necessary topics. Leaving the help library returns you to the parameter prompt.
• Additional information describing the detailed use of the POLKA GUI is available from the Help menu within the GUI.

5.9 Using RA/DEC Information

Information describing spatial co-ordinate Frames can be stored within the WCS component of the standard NDF structure. All NDFs know about “pixel co-ordinates”, but additional co-ordinate Frames can be added. In the context of POLPACK, the co-ordinate Frames most likely to be of interest are celestial co-ordinate systems such as RA/DEC. This information can be used in two ways:

(1)

To annotate the axes of vector maps produced using POLPLOT.

(2)

To align vector maps with other images obtained from elsewhere.

5.9.1 Adding an RA/DEC Calibration to your Data

If you are using dual-beam data, the simplest method is probably to define the RA/DEC calibration once the $O$ and $E$ ray images have been extracted into separate images (i.e. after running POLKA). With single-beam data, you can define the RA/DEC calibration at any point. So, the procedure is:

• For dual-beam data, extract and align the $O$ and $E$ ray intensity images using POLKA. Specify the output images using parameters OUT_O and OUT_E, and give a null value (“!”) for parameter OUT_S since we will be using POLCAL to create the Stokes parameters later.
• Add an RA/DEC calibration to one of the aligned images created by POLKA (it doesn’t really matter which one). This will usually require you to know the RA and DEC of at least two features in the image. See appendix D for a simple description of how to use GAIA (SUN/214) to do this.
• Create a cube of Stokes vectors using POLCAL. Any WCS information is copied from the first input image (given for parameter IN) to the output cube. For this reason, the first input image supplied to POLCAL for parameter IN should be the one containing the RA/DEC calibration created in the previous step.
• Continue to create a catalogue of polarization vectors as normal using POLVEC, POLBIN, etc.

5.9.2 Annotating Axes with RA/DEC Values

After following the above procedure, you should find that POLPLOT automatically annotates your vector map with RA/DEC values. If you want to annotate the axes in pixel co-ordinates for any reason, specify the value “PIXEL” for the FRAME parameter when running POLPLOT. You can also choose to annotate the axes in several other common celestial co-ordinate Frames by supplying suitable values for parameter FRAME. Some examples:

FRAME=GAL - this will result in the axes being annotated with galactic co-ordinates.

FRAME=ECL - this will result in the axes being annotated with ecliptic co-ordinates (referred to the B1950.0 equinox).

Ecliptic and equatorial (RA/DEC) co-ordinates are referred to a specified equinox. The required equinox can be included, in parentheses, following the co-ordinate system name. For instance:

FRAME=EQU(J2000) - this will result in the axes being annotated with RA/DEC referred to the J2000.0 equinox. The RA/DEC calibration stored with the catalogue will be precessed if necessary.

FRAME=ECL(B1983.4) - this will result in the axes being annotated with ecliptic co-ordinates referred to the B1983.4 equinox.

5.9.3 Aligning Vector Maps with Other Images

If you have an image containing a calibration in a suitable celestial co-ordinate system, then you can plot the polarization vectors in alignment with the image. If you follow the procedure described in section 5.7, then the vectors will be aligned automatically with the image. One niggle to watch out for is that both DISPLAY and POLPLOT draw annotated axes, potentially resulting in a bit of a mess! You should normally disable the production of one set of axes by setting parameter AXES to “NO” when running either DISPLAY or POLPLOT.

5.9.4 Re-instating Lost WCS Information in a Catalogue

If you modify a POLPACK catalogue using other software (e.g. TOPCAT or STILTS) it is likely that the WCS information will be removed from the resulting output catalogue, resulting in annotated axes that look wrong and/or incorrect alignment with other data. To correct this, the WCS information can be added back into the catalogue using the POLWCSCOPY command. Say for instance you create catalogue mycat.FIT using POLPACK, and then use STILTS to remove low signal-to-noise vectors, creating a new catalogue selcat.FIT:

The WCS information will be missing from selcat.FIT, and so we need to copy it back again from the original catalogue mycat.FIT:

This creates a third catalogue selcat2.FIT, which is a copy of selcat.FIT but with WCS inherited from mycat.FIT.