Skip to content

virgil.radio_clean

Provisional

May change in any 0.4.x release without a deprecation cycle.

CLEAN deconvolution of complex visibilities. See the radio CLEAN guide.

CLEAN deconvolution of radio visibilities (Cotton–Schwab, multi-scale).

The algorithm and the names of the arguments follow CASA's tclean and WSClean; see the radio CLEAN guide. Not to be confused with virgil.imaging.clean, the gradient-based sparse imager for optical interferometry data.

Provisional

May change in any 0.4.x release without a deprecation cycle.

RadioCleanResult dataclass

The products of clean.

Images are (npix, npix) arrays with row 0 North and column 0 East (the orientation of Image).

Attributes:

Name Type Description
image array

Restored image, Jy/beam.
model array

CLEAN model, Jy per pixel.
residual array

Residual image of the final model, Jy/beam.
psf array

Dirty beam, peak 1.
beam (bmaj_mas, bmin_mas, pa_deg)

Restoring beam.
pixel_scale_mas float
mask array of bool

Where components were allowed (the union over major cycles).
iterations int

Minor-cycle iterations.
stop str

"threshold", "nsigma", "niter", "time_limit" or "no_progress" (no component above the cycle threshold) or "diverged" (the peak residual grew by more than 3.0, relative, over the previous major cycle or the minimum so far, as in tclean; model and residual are then those of the cycle that diverged).
history list of dict

One entry per major cycle: iterations so far, peak residual (Jy/beam), rms (Jy/beam), model flux (Jy), wall time (s), and minor_stop, why the minor cycle that followed ended ("threshold", "diverged" or "niter").

image instance-attribute

model instance-attribute

residual instance-attribute

psf instance-attribute

beam instance-attribute

pixel_scale_mas instance-attribute

mask instance-attribute

iterations instance-attribute

stop instance-attribute

history instance-attribute

__init__(image, model, residual, psf, beam, pixel_scale_mas, mask, iterations, stop, history)

model_visibilities(data, chunk_size=1000000)

The model at the (u, v) points of data: (N,) complex (Jy).

Pass to dataclasses.replace/eqx.tree_at of data.vis to write it back, e.g. to subtract it (data.vis - model).

pb_corrected(pb, pblimit=0.2)

image / pb where the primary-beam gain pb (power, peak 1, e.g. exp(primary_beam(...))) is at least pblimit, else NaN.

write_fits(prefix, ra_deg, dec_deg, freq_hz=None, object_name=None)

Write prefix.image.fits, .model.fits, .residual.fits and .psf.fits (the suffixes of tclean).

The headers hold a SIN WCS centred on the phase centre (ra_deg, dec_deg), BUNIT (Jy/beam, or Jy/pixel for the model), BMAJ/BMIN/BPA, and RESTFRQ if freq_hz is given. Rows are stored South first, as FITS expects.

clean(data, npix, pixel_scale_mas, *, deconvolver='hogbom', scales_mas=None, weighting='natural', robust=0.5, uvtaper=None, niter=1000, gain=0.1, threshold=0.0, nsigma=0.0, cycleniter=-1, cyclefactor=1.0, minpsffraction=0.05, maxpsffraction=0.8, smallscalebias=0.6, psfpatch=256, mask=None, usemask='user', sidelobethreshold=3.0, noisethreshold=5.0, lownoisethreshold=1.5, restoringbeam=None, psfcutoff=0.35, uv_cell=None, chunk_size=1000000, time_limit=None, verbose=False)

Cotton–Schwab CLEAN of complex visibilities, after CASA's tclean.

Major cycles image the exact residual V − M (NUFFT model); minor cycles clean it with a window of the PSF. Arguments are named as in tclean; see the guide for the algorithm and the WSClean equivalents.

Source: Högbom (1974), Clark (1980), Schwab (1984), Cornwell (2008), CASA.

Unlike virgil.imaging.clean it takes complex visibilities and an odd npix. Provisional (new in 0.4.1).

Parameters:

Name Type Description Default
data ComplexVisData
required
npix int

Odd image side, so the PSF peaks on a pixel (Image wants even).

 required
pixel_scale_mas float
required
deconvolver ('hogbom', 'multiscale')

Point components or Gaussians (every minor cycle is Clark's windowed loop: no "clark").

 "hogbom"
scales_mas sequence of float

Multi-scale FWHMs in mas, 0 a point; default 0, 5 and 15 pixels.

 None
weighting

As for dirty_image.

 'natural'
robust

As for dirty_image.

 'natural'
uvtaper

As for dirty_image.

 'natural'
niter (int, float, float)

Total iterations, loop gain, and the peak residual (Jy/beam) to stop at.

 1000
gain (int, float, float)

Total iterations, loop gain, and the peak residual (Jy/beam) to stop at.

 1000
threshold (int, float, float)

Total iterations, loop gain, and the peak residual (Jy/beam) to stop at.

 1000
nsigma float

Also stop below nsigma × the robust rms of the residual.

 0.0
cycleniter int

Iterations per minor cycle (−1: all that remain).

 -1
cyclefactor float

A minor cycle stops at max(threshold, f × peak), f = clip(cyclefactor × PSF sidelobe, minpsffraction, maxpsffraction).

 1.0
minpsffraction float

A minor cycle stops at max(threshold, f × peak), f = clip(cyclefactor × PSF sidelobe, minpsffraction, maxpsffraction).

 1.0
maxpsffraction float

A minor cycle stops at max(threshold, f × peak), f = clip(cyclefactor × PSF sidelobe, minpsffraction, maxpsffraction).

 1.0
smallscalebias (float, int)

Preference for small scales (0 to 1); half-width in pixels of the PSF window subtracted per iteration, at most npix - 1.

 0.6
psfpatch (float, int)

Preference for small scales (0 to 1); half-width in pixels of the PSF window subtracted per iteration, at most npix - 1.

 0.6
mask array of bool

Where to clean; default the whole image.

 None
usemask ('user', 'auto-multithresh')

lownoisethreshold "auto-multithresh" adds regions of the beam-smoothed residual (a simplified CASA version, see the guide).

 "user"
restoringbeam (bmaj_mas, bmin_mas, pa_deg)

Default: fitted to the PSF above psfcutoff.

 None
uv_cell

Density cell in wavelengths (default 1/FoV); visibilities transformed at a time; seconds after which no further major cycle starts; print progress.

 None
chunk_size

Density cell in wavelengths (default 1/FoV); visibilities transformed at a time; seconds after which no further major cycle starts; print progress.

 None
time_limit

Density cell in wavelengths (default 1/FoV); visibilities transformed at a time; seconds after which no further major cycle starts; print progress.

 None
verbose

Density cell in wavelengths (default 1/FoV); visibilities transformed at a time; seconds after which no further major cycle starts; print progress.

 None

Returns:

Type Description
RadioCleanResult

fit_beam(psf, pixel_scale_mas, psfcutoff=0.35)

Gaussian fitted to the main lobe of a PSF, as tclean does.

Source: CASA's psfcutoff fit (the lobe above the cutoff).

Parameters:

Name Type Description Default
psf (n, n) array

Dirty beam, peak 1.

 required
pixel_scale_mas float
required
psfcutoff float

The lobe is the connected region around the peak above this level.

 0.35

Returns:

Type Description
(bmaj_mas, bmin_mas, pa_deg) : tuple

FWHM axes and the position angle of the major axis East of North.

restore(model, residual, beam, pixel_scale_mas)

Restored image in Jy/beam: model convolved with beam, plus the residual.

The kernel is built here, peak 1 as Jy/beam needs, to keep this module off imaging.

Parameters:

Name Type Description Default
model (n, n) array

Jy per pixel.

 required
residual (n, n) array

Jy/beam.

 required
beam (bmaj_mas, bmin_mas, pa_deg)
required
pixel_scale_mas float
required