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: {}

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]
                                        [--beam-cutoff BEAM_CUTOFF]
                                        [--fixed-beam-shape FIXED_BEAM_SHAPE FIXED_BEAM_SHAPE FIXED_BEAM_SHAPE]
                                        [--pb-cutoff PB_CUTOFF]
                                        [--trim-linmos-fits]
                                        [--imaging-strategy IMAGING_STRATEGY]
                                        [--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

--beam-cutoff

Cutoff in arcseconds to use when calculating the common beam to convol to

Default: 150

--fixed-beam-shape

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

--pb-cutoff

Primary beam attenuation cutoff to use during linmos

Default: 0.1

--trim-linmos-fits

Trim the linmos fits files to remove the padding that is added. If True, the output fits files will be smaller but might be different shapes

Default: False

--imaging-strategy

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

--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"""
    beam_cutoff: float = 150
    """Cutoff in arcseconds to use when calculating the common beam to convol to"""
    fixed_beam_shape: tuple[float, float, float] | None = None
    """Specify the final beamsize of linmos field images in (arcsec, arcsec, deg)"""
    pb_cutoff: float = 0.1
    """Primary beam attenuation cutoff to use during linmos"""
    trim_linmos_fits: bool = False
    """Trim the linmos fits files to remove the padding that is added. If True, the output fits files will be smaller but might be different shapes"""
    imaging_strategy: Path | None = None
    """Path to a FLINT imaging yaml file that contains settings to use throughout imaging"""
    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. """