Chapter 4POL-2 Data Reduction – Running pol2map

The previous chapter, Chapter 3, described how pol2map produces $I$, $Q$, and $U$ maps from raw POL-2 data. It showed that this reduction process—-which uses pol2map—comprises three steps.

As with the other Python scripts in Smurf, it is possible to get more information about the available parameters by running either:

% pol2map --help

or the

% smurfhelp pol2map

command.

4.1 How to use pol2map

Before running pol2map directly, it is necessary to ensure that the Starlink environment has been initialised and the Smurf package started (see Section 1.3.2 and Section 1.3.3).

This chapter describes how to run pol2map firstly to produce an initial $I$ map; and then again to produce the final $I$, $Q$, and $U$ maps and a vector catalogue, as described in Section 4.2.

To run pol2map, values should normally be supplied for the following command-line parameters1, in order to produce the initial intensity image. Note that if a parameter description ends with a value in square brackets, it is the default value that will be used for the parameter if no value is supplied on the command line.

 IN A list of input NDFs containing raw POL-2 data. There are many ways in which the list of files can be supplied, as described in the “Specifying Groups of Objects” section of SUN/95. The easiest of these is to create a simple text file containing the names of the raw data files (one per line), and then supply the name of the text file, preceded by an up-caret character ( ^ ), as the value for parameter IN. Note that the specified names of the raw data files can contain wildcards such as “$\ast$” and “?”. The name of the NDF in which to store the total intensity ($I$) map (in pW) incorporating all supplied observations. The supplied file name should either have a file type of .sdf, or no file type at all (in which case .sdf will be appended to the supplied value). Any existing file with the same name will be overwritten. The output NDF in which to return the $Q$ map incorporating all supplied observations. This will be in units of pW. Null (!) should be supplied if no $Q$ map is required. The output NDF in which to return the $U$ map incorporating all supplied observations. This will be in units of pW. Null (!) should be supplied if no $U$ map is required. The name of the directory in which to place the $Q$, $U$, and $I$ maps made from each individual observation supplied via IN, before co-adding them. If null (!) is supplied, the new maps are placed in the same temporary directory (chosen automatically) as all the other intermediate files, and so will be deleted when the script exits (unless the parameter RETAIN is set to be TRUE). Note that these maps are always in units of pW. Each one will contain FITS headers specifying the pointing corrections needed to align the map with the reference map. [!] The name of a directory in which to place the $Q$, $U$, and $I$ time series generated by Smurf calcqu, prior to generating maps from them. If null (!) is supplied, they are placed in the same temporary directory as all the other intermediate files, and so will be deleted when the script exits (unless the parameter RETAIN is set to be TRUE). [!]

Some additional command-line parameters are required when pol2map is used for the second time—as discussed in Section 4.3—to produce the final $I$, $Q$, $U$ maps and vector catalogue2.

 CAT The output FITS vector catalogue. No catalogue is created if null (!) is supplied. Note that, by default, the $Q$, $U$, and ${I}_{\text{p}}$ values in this catalogue will be in units of mJy/beam. [!] Specifies the type of masking to be used within makemap (the same type of masking is used to create all three maps—$I$, $Q$, and $U$). If a non-null value is supplied for MASKOUT1, it specifies the NDF in which to store the AST mask created from the NDF specified by Parameter MASK. Only used if an NDF is supplied for Parameter MASK. [!] If a non-null value is supplied for MASKOUT2, it specifies the NDF in which to store the PCA mask created from the NDF specified by Parameter MASK. Only used if an NDF is supplied for Parameter MASK. [!] The total intensity map to be used for IP correction. The map must be in units of pW. If the same value is supplied for both IOUT and IPREF, the output $I$ map will be used for IP correction. [!] TRUE if a correction for statistical bias is to be made to percentage polarisation and polarised intensity in the output vector catalogue specified by the parameter CAT. [FALSE]

The pol2map command provides many other parameters that may be used to modify its behaviour in various ways. To see a full list, type the following.

% pol2map --help

4.2 pol2map – producing the initial I map

As discussed in Chapter 3, pol2map must first be run on the raw data to produce an initial $I$ map. In this first step:

% pol2map in=^myfiles.list iout=iauto qout=! uout=! mapdir=maps qudir=qudata

where the file myfiles.lis contains a list of the raw data files to be included in the map, and could (for instance) look like this.

% cat myfiles.lis
/jcmtdata/raw/scuba2/s8a/20160125/00043/*
/jcmtdata/raw/scuba2/s8b/20160125/00043/*
/jcmtdata/raw/scuba2/s8c/20160125/00043/*
/jcmtdata/raw/scuba2/s8d/20160125/00043/*

This uses all available data from all four 850 µm sub-arrays, for Observation 43 taken on 2016 January 253. In addition, the data used in this example also come from Observations 56 and 59 taken on 2016 January 11 (UT).

Tip:
An up-caret ( $̂$ ) is required any time the user is reading in a group text file in Starlink. For the map-maker, this includes the configuration file (a group of configuration parameters) and the list of input files (a group of NDFs e.g. in= $̂$ myfiles.lis).

Note that the pol2map script also invokes the  Smurf pol2check command, in order to first ensure that the input files are actually POL-2 files.

Note that qout and uout are set to null values, as no $Q$ or $U$ maps are required to be produced during this initial Step 1 reduction stage.

The following shows the output from running this initial pol2map command.

Logging to file pol2map.log
Calculating Q, U and I time streams from raw analysed intensity data...
1/3: Processing 116 raw data files from observation 20160125_00043 ...
2/3: Processing 116 raw data files from observation 20160112_00059 ...
3/3: Processing 116 raw data files from observation 20160112_00056 ...

>>>>   Making I map from 20160125_00043_0003...

>>>>   Making I map from 20160112_00056_0003...

>>>>   Making I map from 20160112_00059_0003...

Co-adding I maps from all observations:

20160125_00043_0003: Storing pointing corrections of (0.0,0.0) arc-seconds
for future use

20160112_00056_0003: Storing pointing corrections of (1.9,2.8) arc-seconds
for future use

20160112_00059_0003: Storing pointing corrections of (2.1,2.4) arc-seconds
for future use

The files and folders produced by this reduction process are described below.

 pol2map.log A log file containing the output from the various Smurf, Kappa and Polpack commands run as part of the pol2map command (pol2map is actually a Python script that runs various other Starlink tasks behind the scenes in order to perform the bulk of the work). A folder containing the $I$, $Q$, and $U$ time-series data for each sub array for each observation. These are produced by calcqu (see Section 3.4). A folder containing the individual $I$ maps from each separate observation. These will have names that end with $\text{_}$imap.sdf. Output total intensity map. The included term “auto” is used to indicate that it was created using an automatically generated AST mask.

The output $I$ map, iauto.sdf, can be opened and viewed with Gaia.

The maps folder contains the individual $I$ maps from each separate observation:

20160112_00056_0003_imap.sdf  20160112_00059_0003_imap.sdf  20160125_00043_0003_imap.sdf

and the qudata folder contains these files.

s8a20160112_00056_0003_IT.sdf  s8b20160112_00059_0003_IT.sdf  s8c20160125_00043_0003_IT.sdf
s8a20160112_00056_0003_QT.sdf  s8b20160112_00059_0003_QT.sdf  s8c20160125_00043_0003_QT.sdf
s8a20160112_00056_0003_UT.sdf  s8b20160112_00059_0003_UT.sdf  s8c20160125_00043_0003_UT.sdf
s8a20160112_00059_0003_IT.sdf  s8b20160125_00043_0003_IT.sdf  s8d20160112_00056_0003_IT.sdf
s8a20160112_00059_0003_QT.sdf  s8b20160125_00043_0003_QT.sdf  s8d20160112_00056_0003_QT.sdf
s8a20160112_00059_0003_UT.sdf  s8b20160125_00043_0003_UT.sdf  s8d20160112_00056_0003_UT.sdf
s8a20160125_00043_0003_IT.sdf  s8c20160112_00056_0003_IT.sdf  s8d20160112_00059_0003_IT.sdf
s8a20160125_00043_0003_QT.sdf  s8c20160112_00056_0003_QT.sdf  s8d20160112_00059_0003_QT.sdf
s8a20160125_00043_0003_UT.sdf  s8c20160112_00056_0003_UT.sdf  s8d20160112_00059_0003_UT.sdf
s8b20160112_00056_0003_IT.sdf  s8c20160112_00059_0003_IT.sdf  s8d20160125_00043_0003_IT.sdf
s8b20160112_00056_0003_QT.sdf  s8c20160112_00059_0003_QT.sdf  s8d20160125_00043_0003_QT.sdf
s8b20160112_00056_0003_UT.sdf  s8c20160112_00059_0003_UT.sdf  s8d20160125_00043_0003_UT.sdf

4.3 pol2map – producing the I, V, U maps and catalogue

As discussed in Chapter 3, the $I$ map output from the initial run of pol2map is used to derive the final $I$, $Q$, and $U$ maps. If requested, a vector catalogue is also produced.

The second and third steps of the POL-2 data reduction process can be run via a single command.

% pol2map in=qudata/\* iout=iext qout=qext uout=uext mapdir=maps mask=iauto \

The following shows the output from running this second pol2map command. First, pol2map produces new $I$ maps for each map, correcting the position using the correction stored in the old $I$ map4, and then co-adds all the observations.

Logging to file pol2map.log
(existing file pol2map.log moved to pol2map.log.1)

Masking will be based on SNR values in ’iauto’.

>>>>   Making I map from 20160112_00056_0003...

Using pre-calculated pointing corrections of (1.9,2.8) arc-seconds

>>>>   Making I map from 20160125_00043_0003...

Using pre-calculated pointing corrections of (0.0,0.0) arc-seconds

>>>>   Making I map from 20160112_00059_0003...

Using pre-calculated pointing corrections of (2.1,2.4) arc-seconds
Coadding I maps from all observations:

As pol2map continues, the $Q$ and $U$ maps are produced, again with pointing corrections. This is followed by the creation of the output vector catalogue.

>>>>   Making Q map from 20160112_00056_0003...

Using pre-calculated pointing corrections of (1.9,2.8) arc-seconds

>>>>   Making Q map from 20160125_00043_0003...

Using pre-calculated pointing corrections of (0.0,0.0) arc-seconds

>>>>   Making Q map from 20160112_00059_0003...

Using pre-calculated pointing corrections of (2.1,2.4) arc-seconds
Coadding Q maps from all observations:

>>>>   Making U map from 20160112_00056_0003...

Using pre-calculated pointing corrections of (1.9,2.8) arc-seconds

>>>>   Making U map from 20160125_00043_0003...

Using pre-calculated pointing corrections of (0.0,0.0) arc-seconds

>>>>   Making U map from 20160112_00059_0003...

Using pre-calculated pointing corrections of (2.1,2.4) arc-seconds
Coadding U maps from all observations:
Creating the output catalogue: ’mycat’...

45604 vectors written to the output catalogue.

The output of this final run of pol2map is as follows.

 pol2map.log A log file containing the output from the pol2map command. Note previous log files are moved to a new name such as pol2map.log.1. The AST mask used in the creation of the final $I$, $Q$, and $U$ maps. The PCA mask used in the creation of the final $I$, $Q$, and $U$ maps. The total intensity image, created using the external AST and PCA masks described above. The $Q$ map (i.e the intensity of the radiation linearly polarised in the direction parallel or perpendicular to the reference plane), created using an external AST and PCA mask. A folder containing the individual $I$, $Q$, and $U$ maps from each separate observation. These will have names that end with $\text{_}$Imap.sdf, $\text{_}$Qmap.sdf, or $\text{_}$Umap.sdf. The $U$ map (i.e. the intensity of the radiation linearly polarised in the direction $±4{5}^{\circ }$ to the reference plane). The output vector catalogue, containing a range of values derived by pol2map for each pixel contained within the $I$ map.

The maps folder now contains individual $Q$ and $U$ maps, alongside the existing $I$ maps listed below.

20160112_00056_0003_Imap.sdf  20160112_00059_0003_Imap.sdf  20160125_00043_0003_Imap.sdf
20160112_00056_0003_Qmap.sdf  20160112_00059_0003_Qmap.sdf  20160125_00043_0003_Qmap.sdf
20160112_00056_0003_Umap.sdf  20160112_00059_0003_Umap.sdf  20160125_00043_0003_Umap.sdf
20160112_00056_0003_imap.sdf  20160112_00059_0003_imap.sdf  20160125_00043_0003_imap.sdf

4.4 Output vectors from pol2map

The output vector catalogue contains a range of values derived by pol2map for each pixel contained within the $I$ map. Intensity values and errors in the catalogue are expressed in units of mJy/beam. If desired, it is possible to switch the catalogue to units of pW by using Jy=no on the pol2map command line. The columns are listed below.

 X Pixel coordinate at the centre of the pixel Pixel coordinate at the centre of the pixel RA coordinate at the centre of the pixel Dec coordinate at the centre of the pixel Total intensity Error in I Stokes $Q$ parameter Error in Q Stokes $U$ parameter Error in U Percentage polarisation Error in P Angle of polarisation Error in ANG Polarised intensity (${I}_{\text{p}}$) Error in polarised intensity Integer values that indicate if the corresponding vector position is inside the AST mask. If the vector is outside the mask, the corresponding column for the mask will have a blank/null value. Vectors that are inside a mask will have a non-zero integer value for the corresponding column. Each “island” within a mask (i.e. a contiguous group of source pixels) will have a different integer value assigned, starting at 1. All vectors within an island are assigned the integer value of the island. Contains integer values that indicate if the corresponding vector position is inside the PCA mask. Value conventions are the same as for the AST column (above).

4.5 POL-2 FCFs

Inserting POL-2 in front of SCUBA-2 reduces the throughput to SCUBA-2. POL-2 is not a perfect polarimeter. Its wire grid absorbs and scatters incoming signal so the modulation amplitude is lower than for a perfect polarimeter. In addition cross polarisation and depolarisation decreases the modulation amplitude without decreasing the power in the transmitted signal. The first type of inefficiencies can be measured by comparing normal SCUBA-2 maps with and without the polarimeter inserted. Such observations have been done on Uranus, Mars and Jupiter. The second type of losses can be measured with a source of known polarisation.

To convert POL-2 data to astronomical units such as mJy/beam a Flux Conversion Factor, FCF, must be applied to the data. For POL-2, the FCFs are quoted in terms of the non-polarimetric SCUBA-2 FCFs.

POL-2 FCFs are now applied automatically within pol2map when catalogue columns in mJy/beam are required by the user, i.e. if the pol2map parameter JY is set to TRUE (the default option). The current version of pol2map uses the new, revised POL-2 FCFs for 850 µm and 450 µm.

4.6 Changing pixel size in pol2map

Inevitably, as with unpolarised SCUBA-2 data reduction, users will sometimes find it necessary to fine-tune the pol2map reduction process for specific situations.

The bin size within the final vector catalogue is controlled by the BINSIZE parameter in the Smurf pol2map command.

% pol2map binsize=12

Changing the catalogue bin size in this way does not change the pixel size of the maps created pol2map. Instead, the maps are binned up to the requested bin size before the catalogue is created. There is another parameter, called PIXSIZE, which controls the map pixel size, but it is usually advisable to leave this at its default value. This is because the map pixel size can affect the behaviour of the iterative algorithm used to create maps.

1Note the distinction between “command-line parameters” that are supplied on the pol2map command line, and “configuration parameters” that are specified within a configuration file. Values for all configuration parameters are obtained using a single command-line parameter called CONFIG.

2This second usage of pol2map includes both “Run 2” and “Run 3” in Figure 3.1.

3The input files should all be for a single waveband from one or more POL-2 observations. Users should not mix files from different wavebands and/or astronomical regions.

4This correction is found by aligning the old $I$ map with the iauto.sdfmap.