This script reduces a chopped and nodded single-beam polarimetry observation, currently just for Michelle data. The imaging observation should comprise chopped object frames at the angles 0, 45 degrees for each of a multiple-of-two pairs of nod positions, followed by frames at waveplate angles 22.5, 67.5 degrees also for each of a multiple-of-two pairs of nod positions.

For each waveplate angle the recipe makes automatically a calibrated, untrimmed mosaic. The recipe combines the multiple images of the source within each of these mosaics into new frames, and uses those four combined frames to calculate automatically calibrated polarisation images and vectors of the source. See “Output Data” for a list of these images.

It performs a null debiassing, creation and propagation of data variance, difference the integrations for each AB chop-beam pair, bad-pixel masking, difference adjacent nodded pairs, registers the frames, and forms a mosaic. See the “Notes” for further information.

• A variance array is created for each chop beam, first using the read noise, and once the bias is removed, Poisson noise is added.

• A bias frame selected from the calibration system is removed from each beam in CHOP read mode. If no bias frame is available in the CHOP mode, the recipe subtracts a null bias, so the errors will be overestimated in the CHOP read mode; the data array will be unaffected once the beams are differenced. The ARRAY_TESTS recipe files a suitable short-exposure dark as a bias in the calibration system.

• The integrations of the two chop beams are differenced, the first subtracted from the second in each pair.

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

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

• Registration is performed using the telescope offsets transformed to pixels.

• The resampling applies integer shifts of origin. 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 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 frames, the recipe creates mosaics for each chop beam and waveplate angle (modulo 180 degrees). 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 and end UT headers are updated to match that of the last-observed frame contributing to the mosaic.

• For each waveplate angle, the combined source image is made by taking symmetrical areas about each source, such that no pixels are duplicated. Thus the divisions occur at midpoints of the chop throw and the nod separations. These are registered using the nominal chop throws and telescope offsets.

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

• An offset of 0.0 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_NOD_CHOP_ 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 differenced pairs (_dp suffix) frames.

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

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

• The combined source image and neighbourhoods at each waveplate angle in
  $<$m$>$$<$date$>$_$<$group_number$>$_p$<$angle$>$_cab.

• The differenced pairs in $<$i$>$$<$date$>$_$<$obs_number$>$_dp, where $<$i$>$ is the frame prefix.

• 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_NOD_CHOP, POL_ANGLE_NOD_CHOP, NOD_CHOP_APHOT.

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

• Uses the Starlink NDF format and multi-NDF HDS container files.

• 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.

• Error propagation is controlled by the USEVAR parameter.