POL2SCAN

Create Q and U maps from a set of POL-2 " spin&scan" data files

Description:

This script runs SMURF:CALCQU on any raw POL-2 data files specified by parameter IN, to create a set of down-sampled time series files holding Q and U values in each bolometer. These are placed in the directory specified by parameter QUDIR. These time series, together with any Q,U time series files specified directly by parameter IN, are then converted into Q and U maps using SMURF:MAKEMAP. A separate pair of Q and U maps is created for each observation present in the supplied data. These maps, together with any Q,U maps specified by parameter IN, are then coadded to form a final pair of Q and U maps. In addition, a range of information derived from each pair of maps included in the coadd is displayed on the screen, and may also be written to an output text file (see parameter OBSTABLE).

The final Q and U maps, together with the supplied total intensity reference map (see parameter IPREF) are then used to create a vector catalogue and polarised intensity map (see parameters CAT, PI and DEBIAS).

Correction for instrumental polarisation is made only if a value is supplied for parameter IPREF.

By default, the Q, U, I and PI catalogue values, together with the maps specified by parameters " Q" , " U" and " PI" , are in units of Jy/beam (see parameter Jy).

Usage:

pol2scan in q u [cat] [ipref] [config] [pixsize] [qudir] [mapdir] [obstable] [retain] [msg_filter] [ilevel] [glevel] [logfile]

Parameters:

ALIGN = LOGICAL (Read)
If TRUE, and if a non-null value is supplied for parameter REF, then corrections to the telescope pointing are determined and applied when creating the Q and U maps for each observation. To determine this pointing correction for an observation, a total intensity map is created from the raw POL2 data for the observation using the supplied reference map (see parameter REF) to specify the pixel grid. Due to pointing errors, this total intensity map may not be aligned accurately with the reference map (errors of up to 8 arc-seconds have been seen). The positional shift required to minimise the residuals between the shifted total intensity map and the reference map is found, and used to correct the pointing when creating the Q and U map. Note, this option slows down the operation of pol2scan as it requires an extra invocation of smurf:makemap for each observation, to create the total intensity maps (which is not required if ALIGN is FALSE). [TRUE]
CAT = LITERAL (Read)
The output FITS vector catalogue. No catalogue is created if null (!) is supplied. [!]
CONFIG = LITERAL (Read)
The MAKEMAP configuration parameter values to use. If a null value (!) or " def" is supplied, the following defaults will be used:

  ast.zero_snr=3
  ast.zero_snrlo=2
  maptol=0.05
  modelorder=(pca,ext,ast,noi)
  noisecliphigh=3
  numiter=-20
  pca.pcathresh=4
  spikebox=10
  spikethresh=5

If a configuration is supplied, it is used in place of the above default configurations. In either case, the following values are always appended to the end of the used config (whether external or defaulted):

  flagslow = 0.01
  downsampscale = 0
  noi.usevar=1

DEBIAS = LOGICAL (Given)
TRUE if a correction for statistical bias is to be made to percentage polarization and polarized intensity in the output vector catalogue specified by parameter CAT and the polarised intensity map specified by parameter PI. [FALSE]
GLEVEL = LITERAL (Read)
Controls the level of information to write to a text log file. Allowed values are as for " ILEVEL" . The log file to create is specified via parameter " LOGFILE. In adition, the glevel value can be changed by assigning a new integer value (one of starutil.NONE, starutil.CRITICAL, starutil.PROGRESS, starutil.ATASK or starutil.DEBUG) to the module variable starutil.glevel. [" ATASK" ]
ILEVEL = LITERAL (Read)
Controls the level of information displayed on the screen by the script. It can take any of the following values (note, these values are purposefully different to the SUN/104 values to avoid confusion in their effects):
  • " NONE" : No screen output is created

  • " CRITICAL" : Only critical messages are displayed such as warnings.

  • " PROGRESS" : Extra messages indicating script progress are also displayed.

  • " ATASK" : Extra messages are also displayed describing each atask invocation. Lines starting with " > > >" indicate the command name and parameter values, and subsequent lines hold the screen output generated by the command.

  • " DEBUG" : Extra messages are also displayed containing unspecified debugging information.

In adition, the glevel value can be changed by assigning a new integer value (one of starutil.NONE, starutil.CRITICAL, starutil.PROGRESS, starutil.ATASK or starutil.DEBUG) to the module variable starutil.glevel. [" PROGRESS" ]

IN = NDF (Read)
A group of input files. Each specified file must be one of the following types:
  • a raw POL-2 data file

  • a time-series file holding Stokes Q, U or I values

  • a two-dimensional map holding Stokes Q or U values (Q and U maps must be in units of pW). Any combination of the above types can be supplied.

IPBEAMFIX = _LOGICAL (Read)
Should the supplied total intensity reference image (parameter IPREF) be modified so that its beam shape matches the expected IP beam shape at the elevation of each supplied POL2 observation, before doing IP correction? This is currently an experimental feature. [FALSE]
IPFCF = _REAL (Read)
The FCF that should be used to convert the supplied IP REF map to pW. This parameter is only used if the supplied IPREF map is not already in units of pW, and if the FCF is not stored in the FITS extension of the map. The suggested default is the standard FCF for the band concerned (450 or 840). Just press return at the prompt to use this default, or enter a new value if the suggested value is not the FCF that was actually used to create the map. []
IPREF = NDF (Read)
A 2D NDF holding a map of total intensity within the sky area covered by the input POL2 data, in units of pW, mJy/beam, Jy/beam, mJy/arcsec2, Jy/arcsec2 ("^" may be used in place of " " ). If supplied, the returned Q and U maps will be corrected for instrumental polarisation, based on the total intensity values in IPREF. The supplied IPREF map need not be pre-aligned with the output Q and U maps - it will be resampled as necessary using a transformation derived from its WCS information. The total intensity values in this map are also used to calculate the percentage polarisation values stored in the output vector catalogue specified by parameter CAT. [!]
JY = _LOGICAL (Read)
If TRUE, the output catalogue, and the output maps specified by parameters " Q" , " U" and " PI" , will be in units of Jy/beam. Otherwise they will be in units of pW (in this case, the I values in the output catalogue will be scaled to take account of the different FCFs for POL-2 and non-POL-2 observations). Note, the Q and U maps made from individual observations (see parameter MAPDIR) are always in units of pW. [True]
LOGFILE = LITERAL (Read)
The name of the log file to create if GLEVEL is not NONE. The default is " <command >.log" , where <command > is the name of the executing script (minus any trailing " .py" suffix), and will be created in the current directory. Any file with the same name is over-written. The script can change the logfile if necessary by assign the new log file path to the module variable " starutil.logfile" . Any old log file will be closed befopre the new one is opened. []
MAPDIR = LITTERAL (Read)
The name of a directory in which to put the Q and U maps made from each individual observation supplied via " IN" , before coadding them (the QMAP and UMAP parameters specify the final coadded Q and U maps). 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 scrip exists (unless parameter RETAIN is set TRUE). Note, these maps are always in units of pW. [!]
MSG_FILTER = LITERAL (Read)
Controls the default level of information reported by Starlink atasks invoked within the executing script. This default can be over-ridden by including a value for the msg_filter parameter within the command string passed to the " invoke" function. The accepted values are the list defined in SUN/104 (" None" , " Quiet" , " Normal" , " Verbose" , etc). [" Normal" ]
NORTH = LITERAL (Read)
Specifies the celestial coordinate system to use as the reference direction in any newly created Q and U time series files. For instance if NORTH=" AZEL" , then they use the elevation axis as the reference direction, and if " ICRS" is supplied, they use the ICRS Declination axis. If " TRACKING" is supplied, they use north in the tracking system - what ever that may be. [" TRACKING" ]
OBSTABLE = LITERAL (Read)
The path of a new text file to create, to which will be written statistics describined the Q and U maps for each individual observation present in the list of files specified by parameter IN. No file is created if null (!) is supplied. The values are written in the form of a TOPCAT " ascii" table, with one row for each observation. The columns are:
  • UT: UT date of observation

  • OBS: Observation number

  • SUBSCAN: The first subscan included in the map

  • WVM: The mean of the starting and ending WVM tau values

  • NEFD_Q: The measured NEFD in the Q map (mJy.sec^(0.5))

  • NEFD_U: The measured NEFD in the U map (mJy.sec^(0.5))

  • NEFD_EXP: The expected NEFD based on WVM and elevation (mJy.sec^(0.5))

  • TIME: The elapsed time of the data included in the maps (s)

  • SIZE_Q: The total area of the source regions in the Q map (square arc-mins)

  • SIZE_U: The total area of the source regions in the U map (square arc-mins)

  • RMS_Q: The RMS Q value within the source regions (pW)

  • RMS_U: The RMS U value within the source regions (pW)

  • NBOLO_Q: Number of bolometers contributing to Q map

  • NBOLO_U: Number of bolometers contributing to U map

  • DX: Pointing correction in azimuth (arc-sec)

  • DY: Pointing correction in elevation (arc-sec) The last two columns (DX and DY) are only created if parameter ALIGN is TRUE. [!]

PI = NDF (Read)
An output NDF in which to return the polarised intensity map. No polarised intensity map will be created if null (!) is supplied. [!]
PIXSIZE = _REAL (Read)
Pixel dimensions in the output Q and U maps, in arcsec. The default is 4 arc-sec for 850 um data and 2 arc-sec for 450 um data. []
Q = NDF (Read)
The output NDF in which to return the total Q intensity map including all supplied observations.
QUDIR = LITTERAL (Read)
The name of a directory in which to put the Q, U and I time series generated by SMURF:CALCQU. If null (!) is supplied, they are placed in the same temporary direcory as all the other intermediate files. [!]
U = NDF (Read)
The output NDF in which to return the total U intensity map including all supplied observations.
REF = NDF (Read)
An optional map defining the pixel grid for the output maps. If no value is specified for REF on the command line, it defaults to the value supplied for parameter IPREF. See also parameter ALIGN. []
RETAIN = _LOGICAL (Read)
Should the temporary directory containing the intermediate files created by this script be retained? If not, it will be deleted before the script exits. If retained, a message will be displayed at the end specifying the path to the directory. [FALSE]