1 Introduction

A linear polarization spectrum is a set of Stokes vectors $\left(I_{\lambda },Q_{\lambda },U_{\lambda }\right)$. Hence linear spectropolarimetric data is four-dimensional (six-dimensional if the variance arrays of the Stokes parameters are included) and cannot be manipulated using the standard spectral analysis packages (e.g., dipso; Howarth & Murray 1991).

polmap owes much to dipso as far as the style of user interface is concerned, but no attempt was made to provide the wealth of spectral analysis routines available in dipso. The routines provided by polmap are specifically designed for the spectropolarimetrist. The manual includes a simple step-by-step guide to the program and some example data analysis recipes.

1.1 polmap and TSP

The TSP package (Bailey 1990) runs under the ADAM environment and provides many routines for handling time-series and polarimetric data. The TSP routines are biased towards data reduction, and facilities are provided to reduce data from several different instruments. polmap does not contain any data reduction routines, but was designed with data analysis in mind.

polmap also provides routines for displaying data that are not available in TSP. Command are provided to read and write TSP polarization spectrum format files from within polmap. Hence the packages should be seen as complimentary, in a similar manner to figaro and dipso.

1.2 The command interface

Commands may be entered at the prompt in either upper- or lower-case. Numerical parameters must follow the command in the order specified and must be separated by spaces. If any command parameters are omitted on the command line they are usually prompted for. Several commands may be entered on the same command line provided they are separated by commas; the only exception is the COMFILE command, which must appear on its own command line.

If a character string parameter (such as a filename) contains upper-case characters it must be placed in double quotes in order to protect it from the command parser. If a range of integers is required as a parameter to a command a greater-than sign may be employed. For example instead of DELETE 4 5 6 7 the form DELETE 4 > 7 may be used. HELP COMMANDS will give a list of the available commands and you can also obtain help on a specific command using HELP command.

1.3 Data storage

The data storage system is very similar to dipso. The polarization spectra are stored in a stack and spectra may be put onto the top (numerically largest) stack entry or pulled from the middle of the stack. Routines that alter or measure data generally work on the spectrum in the current arrays and results to any operation are generally stored in these arrays as well. The entire stack may be saved in NDF format using the WRSTK command.

1.4 Getting started

In order to run polmap you must source the polmap.csh script. On Starlink systems, the command alias polmapsetup will do this for you if you have initialised the Starlink Software for use.

The polmap.csh script sets the environment variable POLMAP_DIR to point to the location of the polmap files, and defines the command alias polmap to run the polmap exectuable.

Then copy the file sn1987a.sdf from the polmap directory into an empty working directory:

Typing polmap at your normal shell prompt will start the program. A message-of-the-day will appear with any updates or changes to the program and the arrow prompt notifies you that the program is now ready for input.

Data may be read into the program from ascii files (RDALAS), TSP files (RDTSP) or from stack files that were created using polmap (RDSTK). Type rdtsp sn1987a to read in the file demonstration spectrum from your working directory. The case of the input string in unimportant and if parameters are omitted they are normally prompted for. Place character string parameters in quotes to protect them from the command parsing routine. The polarization spectrum is now in the current arrays. The current arrays are the arrays on which most of the polmap commands act and are the arrays to which results of commands are written. The polarization spectrum can be put onto a stack of spectra using the PUT command. Try it now. The program should respond with a short message naming the stack entry in which the spectrum has been copied. It is important to note that although the spectrum has been put onto the stack it is also still in the current arrays. Using PUT again will put another copy of the current spectrum onto the stack. The LIST command will list the stack contents along with some useful information such as the spectral range and the number of data points. Typing LIST 0 will display the contents of the current arrays.

In order to plot the data we must first initialize a graphics device. This is done using the DEV command. The command requires as a parameter a standard GKS device name (eg. xwindows) along with the number of subdivisions in $x$ and $y$ into which the plotting surface must be divided. If $x$ and $y$ are not specified then the defaults ($x=1$,$y=1$) are employed. Once you have initialised your graphics device try typing TRIPLOT 0.03 1. This command will produce a triplot of the data in stack entry 1 (which should be the demonstration spectrum). The top section of the triplot shows the position angle of the polarization (in degrees), the middle sections shows the percentage polarization and the final section is the Stokes $I$ component. Note that the top two sections appear to have a varying bin size. This is because the polarization spectrum is binned to a constant percentage polarization error (of 0.03 percent). This means that regions of the spectrum with smaller errors on Stokes $Q$ and $U$ have a higher spectral resolution. The range over which the spectrum is plotted can be adjusted using TRANGE,PRANGE,IRANGE and WRANGE to limit the position angle, percentage polarization,intensity and wavelength ranges respectively. TAUTO,PAUTO,IAUTO and WAUTO switch off the ranges and let the program autolimit them. The wavelength range can also be set interactively using the CWRANGE command, which uses the cursor.

1.5 A step-by-step analysis example

You should now have two copies of the demonstration data on the stack. Type title demo2 to change the title of the current spectrum and then put it on the stack. Listing the stack you should now find three entries of the same spectrum, so let’s delete some. Typing DEL 1 2 will delete the first and second stack entries. Listing the stack again will show that there is now only one entry, entitled demo2. Triplot this entry and type CONTDEF. This command allows the user to define multiple regions of continuum. Start at the shortward end of the spectrum and define four line-free continuum bins. Define a bin with the end shortward of the start in order to quit the continuum definition. Typing CONTFIT 1 2 will fit a second order polynomial to the three Stokes components of the first stack entry. The fit has been mapped onto the wavelength grid of the current array, so title the fit and put it onto the stack. You can plot the two spectra on the same axes using TRIPLOT 0.03 1 2. Note that the line styles are the same for both the spectra. The LROT command will make the line style change for each plot. In order to rectify the spectrum type IDIV 1. The Stokes $I$ spectrum of the current arrays has been divided into the $I$ array of stack entry number one. The results are now in the current arrays. TRIPLOT 0.03 will plot the current polarization (hopefully rectified) spectrum. Put this onto the stack and then use wrstk junk to write out the entire stack onto disk. The file junk.sdf will be in our current directory. Typing QUIT will leave the program.

1.6 Command files

The COMFILE command may be used to read input from a text file rather than from the keyboard. The COMFILE must be given on its own command line. The text file is simply a list of commands as you would have typed them in. The default extension of a command file is .cmd. A command file may contain a COMFILE command but the nest must be no deeper than twenty files (more than enough hopefully). If you have a set of commands that you regularly issue after starting the program then these may be placed in the file .polmap in your home directory. If found, this command file is executed on start-up. It might contain a DEV command to initialize your specific device type, or a command to set your plotting styles.

1.7 The command history

The COMMS command lists the twenty previous commands. Any of these commands may be accessed using the pling (!) symbol. For example !203 will execute the command number 203 from the command history, in a similar fashion to the UNIX operating system. It should be noted that if commas are used to separate commands then each will be given a separate command history number.