This script reduces a polarimetry observation with UKIRT imaging data. It takes an imaging observation comprising object frames at the four waveplate angles 0, 45, 22.5, 67.5 degrees for each of of a series of jitter positions offset in Right Ascension; and a dark frame to make calibrated polarisation images and vectors automatically. See “Output Data” for a list of these images.

It performs a null debiassing, bad-pixel masking, dark subtraction and flat-field division on all frames. Next the sections of the frame representing the e- and o-beam target and sky regions are extracted, and the target frames sky-subtracted. The resultant frames undergo registration and resampling to form a mosaic for each waveplate angle and beam. Once all eight mosaics are formed they are registered and resampled, and then combined to form the various polarisation images. The polarisation data are binned and noisy data excluded from a final catalogue of vectors. See the “Notes” for details.

This recipe works well for point sources, and for extended sources whose sizes in Right Ascension and Declination are less than about 35 and 15 arcseconds respectively for UFTI, or 9 and 4 arcseconds for IRCAM. Objects which would appear in both the target and sky regions, i.e. Declination extents south of the centre larger than 35 arcseconds (UFTI) or 8 arcseconds (IRCAM), should use recipe POL_EXTENDED for best results.

• A World Co-ordinate System (WCS) using the AIPS convention is created in the headers should no WCS already exist.

• For IRCAM, old headers are reordered and structured with headings before groups of related keywords. The comments have units added or appear in a standard format. Four deprecated headers are removed. FITS-violating headers are corrected. Spurious instrument names are changed to IRCAM3.

• Data errors are propagated through all processing steps. The initial values are found by applying the nominal ADU conversion and read noise.

• The bad-pixel mask applied is $ORAC_DATA_CAL/bpm.

• Each dark-subtracted frame has thresholds applied beyond which pixels are flagged as bad. The lower limit is 5 standard deviations below the mode, but constrained to the range $-$100 to 1. The upper limit is 1000 above the saturation limit for the detector in the mode used.

• You should use SKY_FLAT_POL or SKY_FLAT_POL_ANGLE to make the flat fields.

• The target regions are 30% to 70% of the frame width about the Right-ascension centre, i.e. roughly centred on the source. The current sky limits are 1% to 99% of the frame width along the Right-ascension axis. The Declination pixel limits are instrument dependent, and are as follows. For UFTI, o sky: 69–264; e sky: 320–484; o target: 601–764; e target: 824–988. For IRCAM, o sky: 12–52; e sky: 67–107; o target: 152–192; e target: 207–247.

• The sky subtraction for a beam uses a constant modal sky level from the corresponding sky region.

• Registration is performed using common point sources in the overlap regions. If the recipe cannot identify sufficient common objects for automatic registration, the recipe matches the centroid of central source within an 8-arcsecond box. Should that fail for the jittered e- and o-beam sections, the recipe resorts to using the telescope offsets transformed to pixels. However, the final option for registering the e and o-beam mosaics at different waveplate angles, uses the beam offsets in arcseconds for the current filter converted to pixels.

• The resampling applies non-integer shifts of origin using bilinear interpolation. There is no rotation to align the Cartesian axes with the cardinal directions.

• The recipe makes the mosaics by applying offsets in intensity to give the most consistent result amongst the overlapping regions. The mosaic is not trimmed to the dimensions of a single frame, thus the noise will be greater in the few pixels in the peripheral areas having received less exposure time. The mosaic is not normalised by its exposure time (that being the exposure time of a single frame).

• For each cycle of twelve frames, the recipe creates mosaics for each beam and waveplate angle. Each mosaic has its bad pixels filled and after the first cycle is then added into its own master mosaic of improving signal to noise. The exposure time is also summed and stored in each master mosaic’s corresponding header. Likewise the end airmass header and end UT headers are updated to match that of the last-observed frame contributing to the mosaic.

• The polarised intensity is corrected for the statistical bias of the noise by subtracting the variance of $Q$ or $U$.

• An offset of 6.3 degrees clockwise is applied to the rotation angle for the orientation of the analyser with respect to north. A non-null value will be applied once it is determined.

• The polarisation data for each pixel are also stored in catalogues. See “Output Data”.

• The intensity image may be displayed with vectors overlaid. Steps are taken to reduce the number of noisy or insignificant pixels, as well as clutter. First, the polarisation catalogue data are averaged in 3-by-3-pixel bins. Second, a binned pixel is rejected if its polarisation is greater than 50% or is not positive, or its polarisation signal to noise less than 3, or its polarisation error is greater 5%. The bin size and thresholds can readily be changed by supplying arguments to the _CALC_STOKES_ primitive.

• At the end of each cycle, the grand mosaics are registered, and new polarisation maps and catalogues constructed.

• Intermediate frames are deleted except for the flat-fielded (_ff suffix) frames and the mosaics (_mos or _mos_c$<$cycle_number$>$ suffix).

• The integrated mosaics in $<$m$>$$<$date$>$_$<$group_number$>$_$<$beam$>$$<$angle$>$_mos, where $<$m$>$ the instrument’s group prefix. Token $<$beam$>$ is e or o; and $<$angle$>$ is 0, 22, 45, or 67.

• A mosaic for each cycle of jittered frames per beam and angle in
  $<$m$>$$<$date$>$_$<$group_number$>$_$<$beam$>$$<$angle$>$_mos_c$<$cycle_number$>$, where $<$cycle_number$>$ counts from 0.

• The individual flat-fielded frames in $<$i$>$$<$date$>$_$<$obs_number$>$_ff, where $<$i$>$ is the frame prefix. The naming format is slightly different for some non-UKIRT instruments.

• Polarisation frames $<$m$>$$<$date$>$_$<$group_number$>$_$<$suffix$>$, each with a different suffix for the each parameter. The suffices are:
  

  I	intensity
  P	percentage polarisation
  PI	polarisation intensity
  Q	Stokes $Q$
  TH	polarisation angle
  U	Stokes $U$

• A FITS binary-table catalogue of the binned and culled polarisation data, called $<$m$>$$<$date$>$_$<$group_number$>$_I.FIT. For each point it tabulates the $x$-$y$ co-ordinates, the total intensity, the Stokes parameters, the percentage polarisation, the polarisation angle and intensity. There are additional columns giving the standard deviation on each of the tabulated values (excluding the co-ordinates). Likewise
  $<$m$>$$<$date$>$_$<$group_number$>$_all.FIT and
  $<$m$>$$<$date$>$_$<$group_number$>$_bin.FIT store the full and binned catalogues respectively.

NUMBER = INTEGER

USEVAR = LOGICAL

POL_EXTENDED, POL_JITTER, SKY_FLAT_POL, SKY_FLAT_POL_ANGLE.

• The processing engines are from the Starlink packages: Ccdpack, Kappa, Polpack, Figaro, and Cursa.

• Uses the Starlink NDF format.

• History is recorded within the data files.

• The title of the data is propagated through intermediate files to the mosaics. The polarisation maps have new titles as follows using the suffices described in Output Data. I: Intensity; P: Polarisation; PI: Polarised Intensity; Q: Stokes Q; TH: Polarisation Angle; U: Stokes U.

• The origins of the generated polarisation maps are set to [1,1]. The WCS current frame is unchanged.

• The units are set for the frames with suffices (see “Output Data”) P to %, and TH to degrees.