Chapter 4
POL-2 Data Reduction – Running pol2map

 4.1 How to use pol2map
 4.2 pol2map – producing the initial I map.
 4.3 pol2map – producing the I, Q, U maps and catalogue
 4.4 Output vectors from pol2map
 4.5 POL-2 FCFs
 4.6 Changing pixel size in 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, you can get more information about the available parameters by doing either:

  % pol2map --help

or

  % 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, U maps and vector catalogue as described in Section 4.2 (this is referred to as “Run 1” in Figure 3.1).

To run pol2map, values should normally be supplied for the following command-line parameters1 to produce the initial intensity image (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 Section “Specifying Groups of Objects” in SUN/95. The easiest 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, the names of the raw data files can contain wildcards such as “” and “?”.
IOUT 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.
QOUT The output NDF in which to return the Q map including all supplied observations. This will be in units of pW. Null (!) should be supplied if no Q map is required.
UOUT The output NDF in which to return the U map including all supplied observations. This will be in units of pW. Null (!) should be supplied if no U map is required.
MAPDIR The name of a directory in which to put the Q, U and I maps made from each individual observation supplied via IN, before coadding 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 exists (unless Parameter RETAIN is set TRUE). Note, 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. [!]
QUDIR The name of a directory in which to put 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 exists (unless Parameter RETAIN is set 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 – by default the Q, U and Ip values in this catalogue will be in units of mJy/beam. [!]
MASK 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).
MASKOUT1 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. [!]
MASKOUT2 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. [!]
IPREF 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. [!]
DEBIAS TRUE if a correction for statistical bias is to be made to percentage polarisation and polarised intensity in the output vector catalogue specified by Parameter CAT. [FALSE]

The pol2map command provides many other parameters that can be used to modify its behaviour in various ways. To see a full list, do this.

  % 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

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 for all four 850 μm sub-arrays, for Observation 43 taken on 25th January 20163. In addition, the data used in this example also comes from Observations 56 and 59 taken on January 11th 2016 (UT).

Tip:
An up-caret ( ̂ ) is required any time you are 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).

To check if the files are POL-2 files, run the Smurf command pol2check.

  % pol2check ^myfiles.list

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...
  
  Storing pointing corrections of (0.0,0.0) arc-seconds for future use
  
  >>>>   Making I map from 20160112_00056_0003...
  
  Storing pointing corrections of (1.889022181,2.8085505485) arc-seconds for future use
  
  >>>>   Making I map from 20160112_00059_0003...
  
  Storing pointing corrections of (2.13319187001,2.40199783004) arc-seconds for future use
  Coadding I maps from all observations:

The files and folders produced in this reduction 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. In fact, pol2map is a Python script, which runs various other Starlink tasks behind the scenes to perform the bulk of the work.
qudata/ 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 Chapter 3.3).
maps/ A folder containing the individual I maps from each separate observation _imap.sdf.
iauto.sdf Output total intensity file from an automatically generated astronomical mask.

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


pict
Figure 4.1: The I map, iauto.sdf, as 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, Q, 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 \
            maskout1=astmask maskout2=pcamask ipref=iext cat=mycat debias=yes

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 coadds 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.889022181,2.8085505485) 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.13319187001,2.40199783004) 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.889022181,2.8085505485) 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.13319187001,2.40199783004) arc-seconds
  Coadding Q maps from all observations:
  
  >>>>   Making U map from 20160112_00056_0003...
  
     Using pre-calculated pointing corrections of (1.889022181,2.8085505485) 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.13319187001,2.40199783004) 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.
astmask.sdf The AST mask used in the creation of the final I, Q and U maps.
pcamask.sdf The PCA mask used in the creation of the final I, Q and U maps.
iext.sdf The total intensity image, created using the external AST and PCA mask described above.
qext.sdf 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.
maps/ A folder containing the individual I, Q and U maps from each separate observation _Imap.sdf. _Qmap.sdf and _Umap.sdf.
uext.sdf The U map (i.e. the intensity of the radiation linearly polarised in the direction ± 45 to the reference plane).
mycat.FIT The output vector catalogue containing a range of values derived by pol2map for each pixel contained within the I map.


pict pict
Figure 4.2: Left: I map, iauto, as produced by the automask on the first pass of pol2map. Right: Final I map, iext, as viewed in Gaia. The flatter background is due to the increase in pca.pcathresh.



pict pict
Figure 4.3: Left: Q map, qext.sdf. Right: U map uext.sdf, as viewed with Gaia.


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 values are tabulated below.

X Pixel coordinate
Y Pixel coordinate
RA RA coordinate
Dec Dec coordinate
I Total intensity
DI Error in I
Q Stokes Q parameter
DQ Error in Q
U Stokes U parameter
DU Error in U
P Percentage polarisation
DP Error in P
ANG Angle of polarisation
DANG Error in ANG
PI Polarised intensity (Ip)
DPI Error in polarised intensity

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 polarimiter. Its wire grid absorbs and scatters incoming signal so the modulation amplitude is lower than for a perfect polarimeter. In addition cross polarization and depolarization 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 know polarization.

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 SCUBA-2 FCF.

At 850 µm and 450 µm the FCFs for POL-2 are found to be a factor of 1.35 and 1.96 times higher than the standard SCUBA-2 FCF for 850 µm and 450 µm, respectively.

4.6 Changing pixel size in pol2map

Inevitably, as with unpolarised SCUBA-2 data reduction, it will probably be necessary for you to tweak the pol2map reduction for specific situations.

The pixel size of the final map produced is controlled by the PIXSIZE parameter in the Smurf pol2map command.

  % pol2map pixsize=12

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 – do not mix files from different wavebands and/or astronomical regions

4This correction is found by aligning the old I map with the supplied reference map, or the first observation if no reference map was supplied.