User Parameters - Mosaicking¶
Levels of Mosaicking¶
The default mode of the pipeline is to produce mosaics at several levels for a given scheduling block. Each field in the measurement set will have its own mosaic, combining all requested beams for that field.
There is a choice for how the weighting is done at this step. The
original method was to use
weighttype=FromPrimaryBeamModel, which simply applies a primary beam
correction (given that the weights image is essentially flat for
W-projection). The new default, however, is weighttype=Combined,
which combines the primary beam weighting with the value from the
weights image, better accounting for differences in effective
integration time or flagging. The former method will produce mosaic
weights images normalised to a peak of 1, while the latter does not
apply any normalisation. The choice between the two is made with the
LINMOS_SINGLE_FIELD_WEIGHTTYPE config parameter.
When the scheduling block has used the tilesky mode, the fields in the measurement set will be of the form NAME_Tx-yI, where x & y give the offsets in the tiling grid, and I is one of A,B,C,D, indicating the interleaving offset for that tile position. NAME is some identifying text. In this situation, each x-y tile will have its own mosaic, where the mosaics of each interleave position for that tile are combined.
Finally, the mosaics of all fields and/or tiles are combined to form a single mosaic image for the scheduling block. This second stage of mosaicking is not done if there is only a single field in the measurement set (instead the single field mosaic is copied to the top-level directory at the completion of the initial mosaicking job).
Additionally, if there are multiple fields in the measurement set, but
they should not be mosaicked together (for instance, if they are
quite separate locations on the sky), then you can set
DO_MOSAIC_FIELDS=false. Then the individual fields will be
mosaicked but nothing more.
The default behaviour is to create mosaics with the same direction
type and projection as the beam images (which means J2000 equatorial,
in SIN projection). These can be changed by using
LINMOS_DIRECTION_TYPE and LINMOS_PROJECTION_TYPE. For
instance, to create mosaics in Galactic coordinates, one would set
LINMOS_DIRECTION_TYPE=GALACTIC. The full lists of possible
direction & projection values are linked from linmos (Linear Mosaic Applicator)
(under the outputcentre parameter).
The mosaicking is done for all image product types – continuum images, continuum cubes, and spectral-line cubes. For each type, the mosaicking is done as separate jobs for different image variants. The user may provide a list of codes for these images: available codes are “restored” (restored image), “convrestored” (restored image convolved to a common resolution across PAF beams), “image” (clean model), “residual” (residual flux from the clean model), “altrestored” (restored image made with alternative preconditioning), “contsub” (continuum-subtracted cube, made with the image-based method). The parameters, and their defaults, are as follows for the different types:
- continuum image:
MOSAIC_IMAGECODE_CONT- “restored convrestored altrestored image residual” - continuum cube:
MOSAIC_IMAGECODE_CONTCUBE- “restored convrestored image residual” - spectral cube:
MOSAIC_IMAGECODE_SPECTRAL- “restored contsub image residual”
If codes other than those listed are provided, the pipeline will exit at the start before submitting any jobs.
For the continuum imaging case when self-calibration has been used, a
mosaic can be made of each loop of the self-calibration process. This
is done for each field (ie. each interleave position of each tile),
and can be turned on/off with the parameter MOSAIC_SELFCAL_LOOPS.
Common Resolution across beams¶
Each beam is imaged independently, and will most likely have a
different point-spread-function (PSF). If these images are mosaicked,
the PSF stored in the header of the mosaic is taken from one of them
(indicated by the LINMOS_PSF_REF parameter), and so may not
accurately reflect the PSF in other parts of the image.
To address this, the beam images may be convolved to a common resolution. For the continuum images, this is done with a single task that looks at all the beam images, determines the best common-resolution PSF, and convolves each image to ensure it has that resolution. For the continuum cubes, the determination of the PSF and the convolution are broken up into separate tasks.
If DO_MOSAIC_FIELDS is true, all beam images in all fields are
looked at together, but if false each field is considered
independently.
For the continuum-cube case, there are two options for how the
frequency-dependence of the PSF is dealt with - either to have a
frequency-independent common PSF (total), or to consider each
channel separately (natural).
There are also parameters that allow the user to fix the resolution, impose a maximum major-axis size on the PSF, or force the output PSF to be circular. See the table below.
| Variable | Default | Description |
|---|---|---|
CONVOLVE_MODE_CUBE |
“natural” | Two modes are allowed:
|
RENAME_IMAGES |
true | Whether to rename the restored image to “raw” following the convolution. |
NUM_CORES_CONVOLVE_2D |
20 | The number of cores to be used for the 2D convolution job |
BMAJ_CONVOLVE |
“” | The target value for the major axis of the PSF. If blank, this is determined from the input images. |
BMIN_CONVOLVE |
“” | The target value for the minor axis of the PSF. If blank, this is determined from the input images. |
BPA_CONVOLVE |
“” | The target value for the position angle of the PSF. If blank, this is determined from the input images. |
BMAJ_CUTOFF_CONVOLVE |
“” | The imposed maximum value for the major axis of the PSF. If blank, no maximum value is imposed and the input images completely determine the value. |
BMAJ_CONVOLVE_CONTCUBE |
“” | The target value for the major axis of the PSF. If blank, this is determined from the input image cubes. |
BMIN_CONVOLVE_CONTCUBE |
“” | The target value for the minor axis of the PSF. If blank, this is determined from the input image cubes. |
BPA_CONVOLVE_CONTCUBE |
“” | The target value for the position angle of the PSF. If blank, this is determined from the input image cubes. |
BMAJ_CUTOFF_CONVOLVE_CONTCUBE |
“” | The imposed maximum value for the major axis of the PSF. If blank, no maximum value is imposed and the input images completely determine the value. |
BMAJ_CONVOLVE_ALT |
“” | The target value for the major axis of the PSF for the convolved “alt” (restore preconditioner) images. If blank, this is determined from the input images. |
BMIN_CONVOLVE_ALT |
“” | The target value for the minor axis of the PSF for the convolved “alt” (restore preconditioner) images. If blank, this is determined from the input images. |
BPA_CONVOLVE_ALT |
“” | The target value for the position angle of the PSF for the convolved “alt” (restore preconditioner) images. If blank, this is determined from the input images. |
BMAJ_CUTOFF_CONVOLVE_ALT |
“” | The imposed maximum value for the major axis of the PSF for the convolved “alt” (restore preconditioner) images. If blank, no maximum value is imposed and the input images completely determine the value. |
FORCE_CIRCULAR_PSF_CONVOLVE |
false | If true, the output PSF is forced to be circular. BMIN is set to BMAJ, and BPA is set to 0. |
FORCE_CIRCULAR_PSF_CONVOLVE_ALT |
false | If true, the output PSF for the convolved alt images is forced to be circular. BMIN is set to BMAJ, and BPA is set to 0. |
Beam locations¶
The linmos tools require beam offsets to know where to place the primary beam models. For recent ASKAP scheduling blocks, this is generated in a self-consistent manner using the command-line interfaces to the scheduling block and footprint services. This uses the recorded beam footprint information in the scheduling block parset to regenerate the central location of each beam.
The services are hosted at the MRO, and in the event of an
interruption to service, the use of these can be bypassed by setting
USE_CLI=false. This requires, however, that you have
previously-made metadata files available in the metadata directory (in
particular the footprint file).
Recent observations rely on the src%d.footprint.rotation parameter
in the scheduling block parset to determine the reference angle from
which the pol_axis parameter gives a field-based rotation. Some
scheduling blocks make use of this parameter yet do not report it in
the parset. If this is the case, you can manually specify the
reference value via the FOOTPRINT_PA_REFERENCE parameter in the
configuration file. The scheduling block parset value always takes
precendence.
If you are processing an older SBID, for which the footprint information is not available in the scheduling block, you must specify the footprint information yourself using the parameters given below. It is possible the footprint service does not know about your footprint in this case - we then fall back to using the ACES script footprint.py, which can accept a broader range of footprint names.
For re-processing of BETA data, you will need to set the IS_BETA
parameter (so that the pipeline does not try to access the scheduling
block service), and provide the beam information using the parameters
below.
It may be that you are using a non-standard arrangement that
footprint.py doesn’t cover. In this case you need to directly specify
the LINMOS_BEAM_OFFSETS variable (this is normally set by the
beamArrangements.sh script). Here is an example of how you would do
this (this is for the “diamond” footprint, band 1, PA=0):
LINMOS_BEAM_OFFSETS="linmos.feeds.beam0 = [-0.000, 0.000]
linmos.feeds.beam1 = [-0.000, 1.244]
linmos.feeds.beam2 = [-1.077, 0.622]
linmos.feeds.beam3 = [-1.077, -0.622]
linmos.feeds.beam4 = [-0.000, -1.244]
linmos.feeds.beam5 = [ 1.077, -0.622]
linmos.feeds.beam6 = [ 1.077, 0.622]
linmos.feeds.beam7 = [-2.154, 0.000]
linmos.feeds.beam8 = [ 2.154, -0.000]"
Note that LINMOS_BEAM_OFFSETS is only needed when all beams have
the same centre position (ie. when
IMAGE_AT_BEAM_CENTRES=false). If this is not the case, each beam
image has a different centre, and linmos simply uses that, putting a
primary beam at the centre of each image.
The pipeline allows users to specify the reference direction for the output
mosaics and over-ride the linmos default that uses the direction of a
central beam as the reference direction for the output mosaic.
See FORCE_FIELD_MOSAIC_CENTRES and FIELD_MOSAIC_CENTRE
for details.
Users can specify realistic beam-models (e.g., from holography observations),
to correct for primary beam gains using ASKAP_PB_TT_IMAGE for correcting
the MFS images, and ASKAP_PB_CUBE_IMAGE for correcting the cubes.
Furthermore, full-Stokes beam models derived from holography can be used to
additionally correct leakages of Stokes-I into the other Stokes parameters
in off-axis regions of the beams. See below for more details on these parameters.
If weights are constant across input images being mosaicked, linmos can be
provided with the corresponding ascii text weights files. This feature makes
use of the write.weightslog feature of imager and avoids the need for
weights images that can be very large, especially for cubes (See imager
for details).
Note: Although USE_WEIGHTS_LOG_CONT, USE_WEIGHTS_LOG_CONTCUBE and USE_WEIGHTS_LOG_SPECTRAL
are exposed to the user, these may be safely left to their default values. The pipleine
internally forces these to be consistent with WRITE_WEIGHTS_LOG_CONT,
WRITE_WEIGHTS_LOG_CONTCUBE and WRITE_WEIGHTS_LOG_SPECTRAL respectively.
| Variable | Default | Parset equivalent | Description |
|---|---|---|---|
DO_MOSAIC |
true | none | Whether to mosaic the individual beam images, forming a single, primary-beam-corrected image. |
DO_MOSAIC_FIELDS |
true | none | Whether to mosaic the different fields together (for when there is more than one in the MS). If set to false, only the field-based mosaicking will be done. |
JOB_TIME_LINMOS |
JOB_TIME_DEFAULT (24:00:00) |
none | Time request for mosaicking |
NUM_CORES_CONTCUBE_LINMOS |
"" |
none | Total number of cores used for each of the contcube
mosaicking jobs. If blank (the default), the number used is
equal to the smaller of the number of cores used for the
continuum cube imaging (NUM_CORES_CONTCUBE_SCI) or the
number of continuum channels. |
CORES_PER_NODE_CONTCUBE_LINMOS |
8 | none | Number of cores on each node used for each of the contcube mosaicking jobs. |
NCHAN_PER_CORE_SPECTRAL_LINMOS |
8 | none | Number of channels to be handled at once by a single process
in the spectral-line mosaicking. This should divide evenly
into the number of spectral channels. This will determine the
number of cores assigned to the spectral-line mosaicking,
unless NUM_CORES_SPECTRAL_LINMOS is provided. |
NUM_CORES_SPECTRAL_LINMOS |
"" |
none | Total number of cores used for each of the spectral-line
mosaicking jobs. If blank, the number used is deterined by
the total number of channels and
NCHAN_PER_CORE_SPECTRAL_LINMOS. |
CORES_PER_NODE_SPECTRAL_LINMOS |
20 | none | Number of cores on each node used for each of the spectral-line mosaicking jobs. |
MOSAIC_IMAGECODE_CONT |
"convrestored raw convaltrestored
image residual" |
none | The list of image codes that are made into continuum mosaics. See text for permitted values. Anything else will result in the pipeline exiting before jobs are submitted. |
MOSAIC_IMAGECODE_CONTCUBE |
"convrestored raw image residual" |
none | The list of image codes that are made into continuum cube mosaics. See text for permitted values. Anything else will result in the pipeline exiting before jobs are submitted. |
MOSAIC_IMAGECODE_SPECTRAL |
"restored contsub image residual" |
none | The list of image codes that are made into spectral mosaics. See text for permitted values. Anything else will result in the pipeline exiting before jobs are submitted. |
USE_WEIGHTS_LOG_CONT |
true | write.weightslog (linmos (Linear Mosaic Applicator)) | If true, use weights from imager-generated the text file. Note: It will be set to |
USE_WEIGHTS_LOG_CONTCUBE |
true | write.weightslog (linmos (Linear Mosaic Applicator)) | If true, use weights from imager-generated the text file. Note: It will be set to |
USE_WEIGHTS_LOG_SPECTRAL |
true | write.weightslog (linmos (Linear Mosaic Applicator)) | If true, use weights from imager-generated the text file. Note: It will be set to |
MOSAIC_SELFCAL_LOOPS |
false | none | Whether to make mosaics of each self-calibration loop. |
FOOTPRINT_PA_REFERENCE |
"" |
none | The reference rotation angle for the footprint. This should only be given if the scheduling block parset does not have the common.src.%d.footprint.rotation parameter, or if you want to over-ride that value. If not given, the footprint.rotation value will be used, or (in its absence), zero. |
BEAM_FOOTPRINT_NAME |
diamond | none | The name of the beam footprint. This needs to be recognised by the ACES tool footprint.py, which generates the offsets required by the linmos application. |
BEAM_FOOTPRINT_PA |
0 | none | The position angle of the beam footprint pattern. Passed to footprint.py. |
BEAM_PITCH |
"" |
none | The pitch, or beam spacing, in degrees. Passed to footprint.py. |
FREQ_BAND_NUMBER |
"" |
none | Which frequency band are we in - determines beam arrangement (1,2,3,4). Passed to footprint.py. If not given, the pitch value is used to set the beam separation. The band is overridden by the pitch as well. |
NUM_BEAMS_FOOTPRINT |
36 | none | The number of beams in the footprint. In regular operation, this will be determined from the footprint service, but will need to be specified in the case of non-standard or BETA footprints. |
LINMOS_BEAM_OFFSETS |
no default | feeds.beam{i} (linmos (Linear Mosaic Applicator)) | Parset entries that specify the beam offsets for use by linmos. Needs to have one entry for each beam being mosaicked. See above for an example. Only provide this if running footprint.py is not going to give you what you want (eg. non-standard beam locations). |
LINMOS_BEAM_SPACING |
"1deg" |
feeds.spacing (linmos (Linear Mosaic Applicator)) | Scale factor for beam arrangement, in format like ‘1deg’.
This should not be altered if you are using a standard
footprint from footprint.py (ie. with
BEAM_FOOTPRINT_NAME). |
LINMOS_CUTOFF |
0.2 | linmos.cutoff (linmos (Linear Mosaic Applicator)) | The primary beam cutoff, as a fraction of the peak |
LINMOS_PSF_REF |
0 | linmos.psfref (linmos (Linear Mosaic Applicator)) | Reference beam for PSF (0-based index of the list of beams, not the beam number) - which beam to take the PSF information from. |
LINMOS_SINGLE_FIELD_WEIGHTTYPE |
Combined | linmos.weighttype (linmos (Linear Mosaic Applicator)) | How to do the weighting in the first stage of mosaicking (all beams of a single field). Can be either “Combined” or “FromPrimaryBeamModel”. |
LINMOS_DIRECTION_TYPE |
J2000 | forms part of linmos.outputcentre (linmos (Linear Mosaic Applicator)) | The direction type to be used by the mosaic output from linmos. A list of valid direction types can be found linked from the (linmos (Linear Mosaic Applicator)) page. |
LINMOS_PROJECTION_TYPE |
SIN | forms part of linmos.outputcentre (linmos (Linear Mosaic Applicator)) | The projection type to be used by the mosaic output from linmos. A list of valid projection types can be found linked from the (linmos (Linear Mosaic Applicator)) page. |
FORCE_FIELD_MOSAIC_CENTRES |
true | none | Allows users to define the output mosaic reference direction
set by default to that of a central beam in the input list.
If true, and FIELD_MOSAIC_CENTRE="", then the centres of
the corresponding field is used as reference direction for
the output mosaic.
If this is set to false, linmos will use the default. |
FIELD_MOSAIC_CENTRE |
"" |
linmos.outputcentre (linmos (Linear Mosaic Applicator)) | Using this parameter, users can define a specific RA-Dec to
be used as the reference direction for the output mosaic.
RA-Dec string format "hh:mm:ss.ss,+dd.mm.ss.ss"
You must also set FORCE_FIELD_MOSAIC_CENTRES=true.
For SBIDs with multiple fields, it may be best to allow the
pipeline to derive the reference direction based on the
FORCE_FIELD_MOSAIC_CENTRES parameter. |
| Primary beam correction | |||
OVERRIDE_PB_WEIGHTS_CHECK |
false | none | Whether to ignore the fact that the weights ID for the holography and science observations may differ, and continue on with the pipeline processing. |
OVERRIDE_PB_FOOTPRINT_CHECK |
false | none | Whether to ignore the fact that the footprint parameters for the holography and science observations may differ, and continue on with the pipeline processing. |
ASKAP_PB_TT_IMAGE |
"" |
linmos.primarybeam.ASKAP_PB.image (linmos (Linear Mosaic Applicator)) | The 4D/5D ASKAP primary beam model FITS image to use for
correcting mosaics of MFS images. The 3rd dimension contains
models for Taylor-terms, while the 4th dimension has beams.
The default "" forces the correction using the
analytical PB models in the code (viz., 2D Gaussians). |
ASKAP_PB_TT_IMAGE_NTERM |
3 | linmos.primarybeam.ASKAP_PB.nterms (linmos (Linear Mosaic Applicator)) | The number of Taylor-term planes to use from the specified
ASKAP_PB_TT_IMAGE when generating the correction. |
ASKAP_PB_CUBE_IMAGE |
"" |
linmos.primarybeam.ASKAP_PB.image (linmos (Linear Mosaic Applicator)) | The 4D/5D ASKAP primary beam model FITS image to use for
correcting mosaics of the coarse and fine spectral cubes.
The 3rd dimension contains models for different frequencies.
The correction for images at specific frequencies is derived
using interpolation/scaling scheme adopted in the “linmos”
application.
The default "" forces the correction using the
analytical PB models in the code (viz., 2D Gaussians). |
Off-axis leakage correction¶
The following table summarises the parameters to turn on off-axis leakage correction. For the off-axis correction to take effect, the user must also specify a valid 5D
ASKAP_PB_TT_IMAGE for correcting the continuum images and a valid 5D ASKAP_PB_CUBE_IMAGE for correcting the image cubes (see above for description of the ASKAP_PB model images).
The 5 dimensions referred to for the model beam images are: RA, Dec, Frequency/TaylorTerm, Polarisation and Beam.
| Variable | Default | Parset equivalent | Description |
|---|---|---|---|
REMOVE_LEAKAGE_OFF_AXIS_CONT |
false | linmos.removeleakage (linmos (Linear Mosaic Applicator)) | If true, the 5D beam model specified by ASKAP_PB_TT_IMAGE
will be used to correct leakage of Stokes-I in the off-axis
regions of the single beam continuum images for a given
Stokes parameter being mosaicked. |
REMOVE_LEAKAGE_OFF_AXIS_CONTCUBE |
false | linmos.removeleakage (linmos (Linear Mosaic Applicator)) | If true, the 5D beam model specified by ASKAP_PB_CUBE_IMAGE
will be used to correct leakage of Stokes-I in the off-axis
regions of the single beam coarse cube images for a given
Stokes parameter being mosaicked. |
REMOVE_LEAKAGE_OFF_AXIS_SPECTRAL |
false | linmos.removeleakage (linmos (Linear Mosaic Applicator)) | If true, the 5D beam model specified by ASKAP_PB_CUBE_IMAGE
will be used to correct leakage of Stokes-I in the off-axis
regions of the single beam fine-channel cube images for a given
Stokes parameter being mosaicked.
NB: Currently the pipeline does spectral imaging for Stokes-I
only. So this parameter does not take effect at the moment. |
REMOVE_LEAKAGE_OFF_AXIS_STOKES_V |
true | linmos.removeleakage (linmos (Linear Mosaic Applicator)) | Allos the Stokes V mosaic to be treated differently. If the
relevant REMOVE_LEAKAGE_OFF_AXIS_ parameter is true, then
setting this to false will turn off the removeleakage linmos
parameter for the Stokes V image/cube only. |