### POL2MAP

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

#### Description:

This script creates maps (Q, U and I) and a vector catalogue from a set of POL-2 observation. New observations can be added into the map without the need to re-process previously processed observations. The output maps are all in units of pW.

Note, with the default configuration this script can take up to an hour to run for each observation on a typical SCUBA-2-capabale computer.

Masking of models within makemap (AST, etc) can be based either on the SNR of the map created as the end of each iteration, or on an external map, or on a fixed circle centred on the origin - see parameter MASK.

By default, the Q, U, I and PI catalogue values are in units of mJy/beam (see parameter Jy).

#### Usage:

pol2map in iout qout uout [cat] [config] [pixsize] [qudir] [mapdir] [mask] [masktype] [ipcor] [ipref] [reuse] [ref] [north] [reffcf] [debias] [retain] [maskout1] [maskout2] [msg_filter] [ilevel] [glevel] [logfile]

#### Parameters:

The output FITS vector catalogue. No catalogue is created if null (!) is supplied. Note - currently, the Q, U and PI values in this catalogue will be in units of pW. [!]
Extra parameter values to include in the MAKEMAP configuration used to create both the I maps and the Q/U maps.

In general, it is important that the I, Q and U maps are all created using the same configuration so that they can be compared directly. However, if it is necessary to use a different configuration for I and Q/U maps, the differences may be specified using the ADAM parameters " ICONFIG" and " QUCONFIG" . The ADAM parameter " CONFIG" specifies the configuration parameters that are always used, whether an I map or a Q/U map is being created. In all cases the configuration parameters specified by " CONFIG" are applied first, followed by the configuration parameters specified by " ICONFIG" (if creating an I map) or " QUCONFIG" (if creating a Q or U map). Thus values supplied in " ICONFIG" or " QUCONFIG" over-ride values for the same parameters specified in " CONFIG" .

The configurations specified by CONFIG, ICONFIG and QUCONFIG are applied on top of the following set of default parameters:

^\$STARLINK_DIR/share/smurf/.dimmconfig_pol2.lis
numiter = -200
modelorder=(com,gai,pca,ext,flt,ast,noi)

maptol = 0.05
maptol_mask = $<$undef$>$
maptol_mean = 0
maptol_box = 60
maptol_hits = 1

ast.mapspike_freeze = 5
pca.pcathresh = -150
pca.zero_niter = 0.5
com.zero_niter = 0.5
flt.zero_niter = 0.5
com.freeze_flags = 30

Additional parameters are also set, depending on the value of parameter MASK. If MASK is set to " AUTO" , the following parameters are added to the above default config:

ast.skip = 10
ast.zero_snr = 3
ast.zero_snrlo = 2
ast.zero_freeze = 0.2

pca.pcathresh = -50
pca.zero_snr = 5
pca.zero_snrlo = 3
pca.zero_freeze = -1

com.zero_snr = 5
com.zero_snrlo = 3
com.zero_freeze = -1

flt.zero_snr = 5
flt.zero_snrlo = 3
flt.zero_freeze = -1

If MASK is set to " CIRCLE" , the following parameters are added to the above default config:

ast.zero_circle = 0.0083 (degrees, i.e. 30 arc-seconds)
pca.zero_circle = 0.0038
com.zero_circle = 0.0083
flt.zero_circle = 0.0083

The default value for pca.pcathresh indicated above will be changed if it is too high to allow convergence of the I maps within the number of iterations allowed by numiter.

If MASK is set to the name of an NDF, this script creates fixed masks from the NDF, and the following parameters are added to the above default config:

The above " ref" mask consists of clumps of pixel with SNR greater than 3, extended down to an SNR level of 2. The " mask2" mask consists of clumps of pixel with SNR greater than 5, extended down to an SNR level of 3. However, the above SNR levels are raised if necessary to ensure that the source occupies no more than 20% of the pixels within the " ref" mask, and 10% of the pixels within the " mask2" mask.

The same configuration is used for all three Stokes parameters - I, Q and U with the exception that " com.noflag=1" is added to the configuration when creating maps for Q and U.

If a configuration is supplied using parameter CONFIG, values supplied for any of the above parameters will over-write the values specified above. In addition, the following mandatory values are always appended to the end of the used configuration:

flagslow = 0.01
downsampscale = 0
noi.usevar=1

If null (!) or " def" is supplied, the above set of default configuration parameters are used without change. [" def" ]

##### 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. [FALSE]
The FCF value that is used to convert I, Q and U values from pW to Jy/Beam. If a null (!) value is supplied a default value is used that depends on the waveband in use - 725.0 for 850 um and 962.0 for 450 um. [!]
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" ]
Extra parameter values to include in the MAKEMAP configuration used to create I maps. The values specified by " ICONFIG" are applied after those specified by " CONFIG" . [!]
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" ]

A group of input files. Each specified file must be one of the following types:
• a raw POL-2 data file. Any supplied raw POL-2 data files will be converted into time-series Q,U and I files using SMURF:CALCQU and placed in the directory specified by parameter QUDIR. These will then be converted into maps using SMURF:MAKEMAP, and placed in the directory specified by parameter MAPDIR.

• a time-series file holding Stokes Q, U or I values. Any supplied time-series files will be converted into individual maps (one for each file) using SMURF:MAKEMAP, and placed in the directory specified by parameter MAPDIR. These maps are created only for the required Stokes parameters - as indicated by parameters IOUT, QOUT and UOUT.

• a two-dimensional map holding Stokes Q, U or I values. Any maps must be in units of pW. The final output I map is created by coadding any supplied I maps with the I maps created by this script. These coadded maps are created only for the required Stokes parameters - as indiciated by parameters IOUT, QOUT and UOUT.

Any combination of the above types can be supplied. Note, if parameter REUSE is TRUE, then any required output files that already exist in the directory specified by parameter MAPDIR are re-used rather than being re-created from the corresponding input data.

##### IOUT = NDF (Write)
The output NDF in which to return the total intensity (I) map including all supplied observations. This will be in units of pW. Supply null (!) if the I map is not to be retained on exit. In this case, the I map will only be created if it is needed to create the output vector catalogue (see parameter CAT) and will be deleted on exit.
If TRUE, then IP correction is used when creating Q and U maps, based on the values in the total intensity map specified by parameter IPREF. If FALSE, then no IP correction is performed. The default is TRUE if any Q or U output maps are being created, and FALSE otherwise. []
The total intensity map to be used for IP correction. Only accessed if parameter IPCOR is set TRUE. If null (!) is supplied for IPREF, the map supplied for parameter REF is used. 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. [!]
If TRUE, the I, Q and U values in the output catalogue will be in units of mJy/beam. Otherwise they will be in units of pW. Note, the Q, U and I maps are always in units of pW. The same FCF value is used to convert all three Stokes parameters from pW to mJy/beam, derived from the value supplied for parameter FCF. [TRUE]
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. []
The name of a directory in which to put the Q, U an 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 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. [!]
Determines how the variance information in the final I, Q and U coadded maps (parameters IOUT, QOUT and UOUT) are derived.

If MAPVAR is FALSE, the variances in the coadded maps are calculated by propagating the variance information from the individual observation maps. These variances are determined by makemap and are based on the spread of bolometer I, Q or U values that fall in each pixel of the individual observation map.

If MAPVAR is TRUE, the variances in the coadded maps are determined from the spread of input values (i.e. the pixel values from the individual observation maps) that fall in each pixel of the coadd.

The two methods produce similar variance estimates in the background regions, but MAPDIR=TRUE usually creates much higher on-source errors than MAPDIR=FALSE. Only use MAPDIR=TRUE if you have enough input observations to make the variance between the individual observation maps statistically meaningful. [FALSE]

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):
• " AUTO" : makemap uses automatically generated masks based on the SNR map at the end of each iteration. The SNR levels used are specified by the " xxx.ZERO_SNR" and " xxx.ZERO_SNRLO" configuration parameters (see parameter CONFIG).

• " CIRCLE" : makemap uses a fixed circular mask of radius 60 arc-seconds centred on the expected source position.

• Any other value is assumed to be a group of one or two NDFs that specify the " external" AST and PCA masks to be used. The way in which these NDFs are used depends on the value of parameter MASKTYPE. These NDFs must be aligned in pixel coordinates with the reference map (parameter REF).

[" AUTO" ]

If a non-null value is supplied for MASKOUT, 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 MASKOUT, 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. [!]
Specifies the way in which NDFs supplied for parameter MASK are to be used. This parameter can be set to either of the following values:
• " Signal" : A single NDF should be supplied for parameter MASK holding the astronomical signal level at each pixel within the astronomical field being mapped. It can be in any units, but must have a Variance component. The AST and PCA masks are created from this map by finding all clumps of contiguous pixels above a fixed SNR limit, and then extending these clumps down to a lower SNR limit. For the AST model, the upper and lower SNR limits are of 3.0 and 2.0. For the PCA mask, the limits are 5.0 and 3.0. The AST and PCA masks created in this way can be saved using parameters MASKOUT1 and MASKOUT2.

• " Mask" : A pair of NDFs should be supplied for parameter MASK, each holding a mask in which background pixels have bad values and source pixels have good values. The first supplied NDF is used directly as the AST mask, and the second is used as the PCA mask.

[" Signal" ]

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" ]
The name of a text file to create, in which to put the paths of all the new maps written to the directory specified by parameter MAPDIR (one per line). If a null (!) value is supplied no file is created. [!]
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" ]
Pixel dimensions in the output I maps, in arcsec. The default is 4 arc-sec for 850 um data and 2 arc-sec for 450 um data. []
##### QOUT = NDF (Write)
The output NDF in which to return the Q map including all supplied observations. This will be in units of pW. Supply null (!) if no Q map is required.