Polarisation imaging

flint supports full-Stokes imaging, with a particular emphasis on supporting polarisation cubes. The main entry point to polarisation imaging is flint_flow_polarisation_pipeline. This flow assumes that the input visibilities are already calibrated to the user’s satisfaction, and simply provides an interface to imaging in Stokes I, Q, U and V. Whilst WSClean typically doesn’t produce ‘cubes’ in the same fashion as ASKAPsoft or CASA (see notes here), flint utilises fitscube to combine the per-channel images into a single FITS file.

Currently, we require the filenames of the input data to follow either the flint or CASDA naming scheme. In the latter case, appropriate transformations will be applied to the data to allow the use of WSClean.

Configuration

The same imaging strategy file can be used for both polarisation imaging and self-calibration. Similar to selfcal, the section for polarisation imaging is called polarisation, with the following three subsections:

  • total: Options for Stokes I. Will always set -pol I in the WSClean command.

  • linear: Options for Stokes Q and U. Will always set -pol QU in the WSClean command.

  • circular Options for Stokes V. Will always set -pol V in the WSClean command.

Currently, only the wsclean options will be used by the polarisation section. The values from defaults will propagate, as expected. For example, assuming the required values have been set in defaults a polarisation section could look like:

polarisation:
  total:
    wsclean:
      squared_channel_joining: false
      no_mf_weighting: true
  linear:
    wsclean:
      join_polarizations: true
      squared_channel_joining: true
      no_mf_weighting: true
      multiscale: false
      local_rms: false
  circular:
    wsclean: {}

Angular resolution

The restoring beam of an ASKAP image varies across the footprint and with frequency, so the per-beam channel images have to be brought to a common resolution before linmos co-adds them. flint does this in the ‘natural’ sense of RACS-tools: one common beam is solved per channel and the cube keeps its frequency-dependent resolution, rather than every channel being dragged out to the coarsest beam in the band.

A channel’s beam is solved over every footprint beam of every Stokes at that channel, so channel N of I, Q and U share one resolution and a per-channel polarisation product (e.g. polarised intensity) is meaningful.

Three options steer this:

  • --cube-beam-cutoff: a beam coarser than this, in arcseconds, is left out of the per-channel solve and its image is blanked instead of convolved. A channel where every image is beyond the cutoff has no beam to convolve to at all, so the whole channel is blanked and marked as carrying no PSF.

  • --mfs-beam-cutoff: the same, for the MFS image/model/residual products. An MFS product has no frequency axis for the beam to vary over, so it gets a single common beam of its own rather than the one the coarsest channel of the cube needed, and a cutoff of its own to go with it.

  • --fixed-beam-shape: convolve every channel to this (arcsec, arcsec, deg) beam instead of solving one, which gives a cube of constant resolution.

Spectro-polarimetric imaging in WSClean

We encourage users to carefully read the WSclean documentation. In practice, we have encountered a few common ‘gotchas’ when producing polarisation cube. As always, a user should pay attention to the output logs to see e.g. how many iterations have been performed and what the stopping criterion was. We also encourage the inspection of image, model, and residual products to see how well (or not) deconvolution has performed.

As of writing, these generally apply to wsclean <= 3.5 and may change with future releases:

  • Using -squared-channel-joining with -multiscale is known to get stuck.

  • Enabling -squared-channel-joining appears to change how image statistics should be interpreted. We have not confirmed this directly, but in seems in practice one should square the values for -auto-mask and -auto-threshold when squared channels are enabled. For example, if you wanted -auto-mask 5 in Stokes I, you should set -auto-mask 25 for Stokes Q and U when using -squared-channel-joining. There also appears to be a bug when -local_rms is also enabled.

  • The WSclean docs recommend turning multi-frequency weighting off when using the individual channel images for science.

Accessing via the CLI

usage: flint_flow_polarisation_pipeline [-h] [--cli-config CLI_CONFIG]
                                        [--cluster-config CLUSTER_CONFIG]
                                        [--expected-ms EXPECTED_MS]
                                        [--wsclean-container WSCLEAN_CONTAINER]
                                        [--yandasoft-container YANDASOFT_CONTAINER]
                                        [--casa-container CASA_CONTAINER]
                                        [--holofile HOLOFILE]
                                        [--mfs-beam-cutoff MFS_BEAM_CUTOFF]
                                        [--cube-beam-cutoff CUBE_BEAM_CUTOFF]
                                        [--fixed-beam-shape FIXED_BEAM_SHAPE FIXED_BEAM_SHAPE FIXED_BEAM_SHAPE]
                                        [--total-resolution-cubes]
                                        [--compress-cubes COMPRESS_CUBES]
                                        [--pb-cutoff PB_CUTOFF] [--bane-noise]
                                        [--imaging-strategy IMAGING_STRATEGY]
                                        [--pol-cube-channel-width POL_CUBE_CHANNEL_WIDTH]
                                        [--sbid-copy-path SBID_COPY_PATH]
                                        flint_ms_directory

Positional Arguments

flint_ms_directory

Path to directories containing the beam-wise flint-calibrated MeasurementSets.

Named Arguments

--cli-config

Path to configuration file

--cluster-config

Path to a cluster configuration file, or a known cluster name.

Default: 'petrichor'

Inputs for PolFieldOptions

Polarisation processing options

--expected-ms

The expected number of measurement set files to find

Default: 36

--wsclean-container

Path to the singularity wsclean container

--yandasoft-container

Path to the singularity yandasoft container

--casa-container

Path to the singularity CASA container

--holofile

Path to the holography FITS cube that will be used when co-adding beams

--mfs-beam-cutoff

Cutoff in arcseconds to use when calculating the common beam the MFS images are convolved to

Default: 150

--cube-beam-cutoff

Cutoff in arcseconds to use when calculating the common beam each cube channel is convolved to

Default: 150

--fixed-beam-shape

Specify the final beamsize of linmos field images in (arcsec, arcsec, deg)

--total-resolution-cubes

Also write cubes at one beam covering the whole band, which RM synthesis needs

Default: False

--compress-cubes

Overrides the strategy fitscube compress setting. None honours the strategy

--pb-cutoff

Primary beam attenuation cutoff to use during linmos

Default: 0.1

--bane-noise

Measure a background and RMS cube off the co-added planes with BANE. Parameters come from the strategy’s fftbane mode. Independent of RMSynthFieldOptions.bane_noise

Default: False

--imaging-strategy

Path to a FLINT imaging yaml file that contains settings to use throughout imaging

--pol-cube-channel-width

Desired width, in Hz, of each plane of the polarisation cubes. The wsclean channel division is solved for this target so the cubes have a single linear frequency axis, overriding the strategy channels_out. Deliberately separate from RACSAllOptions.cube_channel_width, as the continuum and polarisation cubes need not share a channelisation. See flint.imager.channel_division

--sbid-copy-path

Path that final processed products will be copied into. If None no copying of file products is performed. See ArchiveOptions.

The PolFieldOptions class

Embedded below is the flint Options class used to drive the flint_flow_polarisation_pipeline workflow. Input values are validated by pydantic to ensure they are appropriately typed.

class PolFieldOptions(BaseOptions):
    """Container that represents the flint related options that
    might be used throughout components related to the actual
    pipeline.

    In its present form this `PolFieldOptions` class is not intended
    to contain properties of the data that are being processed,
    rather how those data will be processed.

    These settings are not meant to be adjustable across different polarisations.
    """

    expected_ms: int = 36
    """The expected number of measurement set files to find"""
    wsclean_container: Path | None = None
    """Path to the singularity wsclean container"""
    yandasoft_container: Path | None = None
    """Path to the singularity yandasoft container"""
    casa_container: Path | None = None
    """Path to the singularity CASA container"""
    holofile: Path | None = None
    """Path to the holography FITS cube that will be used when co-adding beams"""
    mfs_beam_cutoff: float = 150
    """Cutoff in arcseconds to use when calculating the common beam the MFS images are convolved to"""
    cube_beam_cutoff: float = 150
    """Cutoff in arcseconds to use when calculating the common beam each cube channel is convolved to"""
    fixed_beam_shape: tuple[float, float, float] | None = None
    """Specify the final beamsize of linmos field images in (arcsec, arcsec, deg)"""
    total_resolution_cubes: bool = False
    """Also write cubes at one beam covering the whole band, which RM synthesis needs"""
    compress_cubes: bool | None = None
    """Overrides the strategy ``fitscube`` compress setting. None honours the strategy"""
    pb_cutoff: float = 0.1
    """Primary beam attenuation cutoff to use during linmos"""
    bane_noise: bool = False
    """Measure a background and RMS cube off the co-added planes with BANE. Parameters come from the strategy's ``fftbane`` mode. Independent of ``RMSynthFieldOptions.bane_noise``"""
    imaging_strategy: Path | None = None
    """Path to a FLINT imaging yaml file that contains settings to use throughout imaging"""
    pol_cube_channel_width: float | None = None
    """Desired width, in Hz, of each plane of the polarisation cubes. The wsclean channel division is solved for this target so the cubes have a single linear frequency axis, overriding the strategy ``channels_out``. Deliberately separate from ``RACSAllOptions.cube_channel_width``, as the continuum and polarisation cubes need not share a channelisation. See ``flint.imager.channel_division``"""
    sbid_copy_path: Path | None = None
    """Path that final processed products will be copied into. If None no copying of file products is performed. See ArchiveOptions. """