name: wsclean description: Radio interferometry imaging and deconvolution tool

WSClean Skill

WSClean is a radio interferometry imaging tool that creates cleaned images from Measurement Sets. Use this skill when working with radio astronomy data from telescopes like LOFAR, MWA, VLA, ASKAP, or SKA.

When to Use

Imaging radio interferometry data from Measurement Set (.ms) files
CLEAN deconvolution of visibility data
Multi-scale cleaning for resolved sources
Multi-frequency synthesis (wideband imaging)
Polarimetric imaging
Facet-based imaging with direction-dependent corrections
Self-calibration loops (model generation)

Docker Access

WSClean is complex to compile. Use Docker:

docker run --rm -it d3vnull0/rapthor-mildtec:smoke wsclean [options] <input.ms>

Mount data directories: -v /host/path:/container/path:rw

Basic Command Structure

wsclean [options] <input-ms> [<2nd-ms> [...]]

Critical: Multiple measurement sets MUST be phase-rotated to same position.

Essential Parameters

Image Setup (Always Required)

-size <w> <h> - Image dimensions in pixels (must be even)
-scale <value> - Pixel scale (e.g., 2asec, 1amin, 0.01deg)
-name <prefix> - Output filename prefix (default: 'wsclean')

Deconvolution Control

-niter <n> - Max iterations (set high, e.g., 1000000)
-auto-threshold <sigma> - Stop at sigma×RMS (recommended: 1-5)
-mgain <gain> - Major loop gain: 0.85 (safe), 0.95 (aggressive)
- Critical: mgain=1.0 prevents self-cal (no MODEL_DATA updates)
-auto-mask <sigma> - Auto-masking threshold (recommended with -auto-threshold)

Weighting

-weight briggs <robust> - Briggs weighting (-2 to +2, common: -0.5, 0, 0.5)
-weight uniform - Maximum resolution
-weight natural - Maximum sensitivity

Advanced Features

-multiscale - Multi-scale CLEAN for resolved sources
-channels-out <n> - Split bandwidth into N images
-join-channels - Multi-frequency deconvolution
-pol <list> - Polarizations: I, Q, U, V, or XX, XY, YX, YY
-join-polarizations - Polarimetric deconvolution

Common Workflows

1. Quick Dirty Image (No Cleaning)

docker run --rm -v $(pwd):/data:rw d3vnull0/rapthor-mildtec:smoke \
  wsclean -size 2048 2048 -scale 5asec -name quick /data/obs.ms

2. Standard Clean

wsclean -size 4096 4096 -scale 2asec \
  -niter 100000 -auto-threshold 3 \
  -weight briggs 0 -mgain 0.85 \
  -name standard obs.ms

3. Deep Multi-Scale Clean (Best Quality)

wsclean -size 8192 8192 -scale 1asec \
  -multiscale -multiscale-scale-bias 0.7 \
  -niter 1000000 -auto-threshold 1 -auto-mask 5 \
  -weight briggs -0.5 -mgain 0.85 \
  -name deep obs.ms

4. Multi-Frequency Synthesis (4 channels)

wsclean -size 4096 4096 -scale 2asec \
  -channels-out 4 -join-channels \
  -multiscale -niter 500000 \
  -auto-threshold 3 -mgain 0.85 \
  -name mfs obs.ms

5. Polarimetric Imaging

wsclean -size 4096 4096 -scale 2asec \
  -pol xx,yy -join-polarizations \
  -niter 100000 -auto-threshold 3 \
  -mgain 0.85 -name pol obs.ms

6. Self-Calibration Imaging

# CRITICAL: mgain < 1.0 to update MODEL_DATA
wsclean -size 4096 4096 -scale 2asec \
  -niter 100000 -auto-threshold 3 \
  -mgain 0.85 -multiscale -auto-mask 5 \
  -name selfcal obs.ms

Output Files

With -name myimage:

myimage-dirty.fits - Dirty image
myimage-image.fits - Cleaned/restored image
myimage-model.fits - Model (CLEAN components)
myimage-residual.fits - Residual after cleaning
myimage-psf.fits - Point spread function

Multi-channel: myimage-0000-image.fits, myimage-0001-image.fits, etc. Multi-pol: myimage-I-image.fits, myimage-Q-image.fits, etc.

Quick Reference - Key Parameters

Parameter	Purpose	Typical Values
`-niter`	Max iterations	100000-1000000
`-auto-threshold`	Stop at N×sigma	1-5 (lower=deeper)
`-mgain`	Major loop gain	0.85 (safe), 0.95 (fast)
`-auto-mask`	Masking threshold	3-5 sigma
`-weight briggs`	Weighting robustness	-0.5 (res), 0 (balanced), 0.5 (sens)
`-multiscale-scale-bias`	Scale preference	0.6-0.7
`-channels-out`	Output channels	4-16 typical
`-j`	CPU threads	Default: all cores

Common Issues

Cleaning Diverges

Lower -mgain to 0.7 or 0.8
Use -multiscale-gain 0.1 if multi-scale
Try -major-iteration-mode single

Out of Memory

Use -abs-mem 32 (or appropriate GB)
Reduce -size or increase -scale
Use -deconvolution-channels for spectral imaging

Can't Self-Calibrate

Ensure mgain < 1.0 (not 1.0!)
MODEL_DATA column only updated with mgain < 1

Poor Image Quality

Use -multiscale for resolved sources
Add -auto-mask 5 for deep cleaning
Check weighting: try -weight briggs 0

When to Consult Detailed References

For complex scenarios, refer to the reference files in this directory:

reference/parameters.md - Complete parameter documentation
reference/workflows.md - Advanced workflows (facets, primary beam, etc.)
reference/troubleshooting.md - Detailed troubleshooting guide

Use the Read tool to access these files when needed.

Best Practices

Always use -auto-threshold (not absolute threshold)
Set high -niter and let threshold stop cleaning
Use mgain 0.85 for robust Cotton-Schwab cleaning
Multi-scale for resolved sources - always better than Högbom
Combine -auto-mask 5 with -auto-threshold 1 for deep cleaning
Image dimensions must be even - preferably power of 2
~5-6 pixels per synthesized beam for proper sampling

Documentation

Full docs: https://wsclean.readthedocs.io/
Algorithm paper: Offringa & Smirnov 2017 (https://arxiv.org/abs/1706.06786)

d3v-null/wsclean-skill