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

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

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

## Basic Command Structure

```bash
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)
```bash
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
```bash
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)
```bash
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)
```bash
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
```bash
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
```bash
# 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

1. **Always use `-auto-threshold`** (not absolute threshold)
2. **Set high `-niter`** and let threshold stop cleaning
3. **Use mgain 0.85** for robust Cotton-Schwab cleaning
4. **Multi-scale for resolved sources** - always better than Högbom
5. **Combine `-auto-mask 5` with `-auto-threshold 1`** for deep cleaning
6. **Image dimensions must be even** - preferably power of 2
7. **~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)