Implementing custom strategies in Python

WSClean has an option to call a Python script instead of using one of its built-in approaches to perform the deconvolution. The option is called -python-deconvolution and takes as parameter the filename of the Python script, e.g.:

wsclean -python-deconvolution my_deconvolution_script.py \
  -niter 1000 -auto-threshold 5 -mgain 0.8 input.ms

The Python script should declare a function with the name and signature deconvolve(residual, model, psf, meta). The first three parameters are numpy arrays. Both residual and model are 4-dimensional arrays with dimensions n_channels * n_polarizations * height * width. The psf is a 3-dimensional cube with dimensions n_channels * height * width; it does not have the polarization dimension because the PSF is assumed to be the same for all polarizations. The meta parameter is a dictionary with various meta information about the data or run:

  • meta.major_iter_threshold: Current requested major iteration threshold.

  • meta.final_threshold: Requested absolute final threshold. If a relative stopping threshold was specified, it is converted to an absolute value before calling this function.

  • meta.mgain: Requested major loop gain.

  • meta.iteration_number: Total number of iterations performed. The deconvolution function is responsible for updating this value.

  • meta.max_iterations: Requested maximum number of iterations.

  • meta.channels: An array, where each element has the properties frequency and weights.

  • meta.square_joined_channels: Set to True when the user has requested squared channels during joining.

  • meta.spectral_fitter: An object that can apply the user-requested spectral fitting (see Wideband deconvolution). It has two methods that each take a spectrum, which is a list of n_channels flux density values.

    • fit(spectrum): returns the fitted coefficients

    • fit_and_evaluate(spectrum): returns the fitted spectrum

There are a few example Python files in the wsclean/scripts/python-examples directory of the repository, notably:

  • simple-deconvolution-example.py, which is a single-frequency, single-polarization algorithm that is similar to a basic clean method. It demonstrates the interface (note that it is slow and not aimed at performance comparisons).

  • mf-deconvolution-example.py, a similar algorithm, but this one makes use of the spectral fitter to demonstrate multi-frequency deconvolution.