wsclean(1)

🌸 WSClean — from the wsclean(1) manual, General Commands Manual 🌸

okay bestie, sit down, hydrate, because this is THE tool. welcome to wsclean(1), the manual page for the icon itself. it's long so we're doing this in parts — part 1, right here, right now. let's go 💅

---

✨ NAME ✨

WSClean — fast generic widefield interferometric imager. that's it, that's the vibe, she's fast, she's generic, she does widefield, she images. 👑

---

🦋 SYNOPSIS 🦋

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

you feed her options and one or more measurement sets. she does the rest. periodt.

---

💖 DESCRIPTION 💖

WSClean (short for w-stacking clean) is a fast generic widefield imager. it uses the w-stacking algorithm, and can also make use of the w-snapshot algorithm. as of Feb 2014, it is 2-12 times faster than CASA's w-projection, depending on the array configuration — yes, depending on the array config, so your mileage may vary, but still. slay.

it supports full-sky imaging and proper beam correction for homogeneous dipole arrays such as the MWA. 💫

WSClean allows Hogbom and Cotton-Schwab cleaning, and can clean polarizations joinedly. all operations are performed on the CPU — so heads up, she is not specialized for GPUs. it's giving CPU main character energy, and honestly? we respect it. 🫶

---

🌈 OPTIONS 🌈

🎀 GENERAL OPTIONS 🎀

• -version — prints WSClean's version and then dips out (exits). bye! 👋
• -j <threads> — tell her how many computing threads to use, i.e. how many cpu cores get to come to the party. Default: use all cpu cores. go big or go home.
• -mem <percentage> — limit memory usage to the given fraction of the total system memory. this is an approximate value, so don't come for her if it's not pixel-perfect. Default: 100.
• -absmem <memory limit> — like -mem, but this one specifies a fixed amount of memory in gigabytes. no fractions, just vibes and gigs.
• -reorder, -no-reorder — force or disable reordering of the Measurement Set. reordering can be faster when the measurement set needs to be iterated several times, like with many major iterations or in channel imaging mode. Default: only reorder when in channel imaging mode.
• -tempdir <directory> — set the temporary directory used when reordering files. Default: same directory as the input measurement set.
• -no-dirty — do not save the dirty image. she simply will not.
• -saveweights — save the gridded weights into a fits file named <image-prefix>-weights.fits.
• -saveuv — save the gridded uv plane, i.e. the FFT of the residual image. the UV plane is complex, hence two images will be output: <prefix>-uv-real.fits and <prefix>-uv-imag.fits. two files, one iconic moment. ✨
• -apply-primary-beam — calculate and apply the primary beam, and save images for the Jones components, with weighting identical to the weighting as used by the imager. Only available for LOFAR. sorry to everyone else, this one's LOFAR-exclusive.
• -reuse-primary-beam — if a primary beam image exists on disk, reuse those images (not implemented yet). so like… she's manifesting it. 🙈
• -use-differential-lofar-beam — assume the visibilities have already been beam-corrected for the reference direction.
• -update-model-required (default), -no-update-model-required — these two options specify whether the model data column is required to contain valid model data after imaging. it can save time to not update the model data column.
• -verbose (or -v) — increase verbosity of output. she will simply tell you more. 🗣️
• -log-time — add date and time to each line in the output. timestamps, because receipts matter.
• -quiet — do not output anything but errors. silent treatment, but make it useful.

---

⚖️ WEIGHTING OPTIONS ⚖️

• -weight <weightmode> — weightmode can be: natural, uniform, briggs. Default: uniform. when using Briggs' weighting, add the robustness parameter, like: -weight briggs 0.5.
• -superweight <factor> — increase the weight gridding box size, similar to Casa's superuniform weighting scheme. Default: 1.0. the factor can be rational and can even be less than one for subpixel weighting. flexible queen.
• -mfsweighting — in spectral mode, calculate the weights as if the image was made using MFS. this makes sure that the sum of channel images equals the MFS weights. otherwise, the channel image will become a bit more naturally weighted. this is only relevant for weighting modes that require gridding (i.e., Uniform, Briggs'). Default: off, unless -joinchannels is specified.
• -nomfsweighting — opposite of -mfsweighting; can be used to turn off MFS weighting in -joinchannels mode.
• -weighting-rank-filter <level> — filter the weights and set high weights to the local mean. the level parameter specifies the filter level; any value larger than level*localmean will be set to level*localmean.
• -weighting-rank-filter-size <size> — set size of the weighting rank filter. Default: 16.
• -taper-gaussian <beamsize> — taper the weights with a Gaussian function. this will reduce the contribution of long baselines. the beamsize is by default in asec, but a unit can be specified ("2amin").
• -taper-tukey <lambda> — taper the outer weights with a Tukey transition. lambda specifies the size of the transition; use in combination with -maxuv-l.
• -taper-inner-tukey <lambda> — taper the weights with a Tukey transition. lambda specifies the size of the transition; use in combination with -minuv-l.
• -taper-edge <lambda> — taper the weights with a rectangle, to keep a space of lambda between the edge and the gridded visibilities.
• -taper-edge-tukey <lambda> — taper the edge weights with a Tukey window. lambda is the size of the Tukey transition. when -taper-edge is also specified, the Tukey transition starts inside the inner rectangle. nested tapers, we love a layered look. 🎀

---

🧚 INVERSION OPTIONS 🧚

• -name <image-prefix> — use image-prefix as the prefix for output files. Default is 'wsclean'.
• -size <width> <height> — Default: 2048 x 2048.
• -trim <width> <height> — after inversion, trim the image to the given size. ✂️
• -scale <pixel-scale> — scale of a pixel. default unit is degrees, but it can be specified, e.g. -scale 20asec. Default: 0.01deg.
• -nwlayers <nwlayers> — number of w-layers to use. Default: minimum suggested #w-layers for the first MS.
• -nwlayers-for-size <width> <height> — use the minimum suggested w-layers for an image of the given size. can e.g. be used to increase accuracy when predicting a small part of the full image.
• -channelsout <count> — splits the bandwidth and makes count nr. of images. Default: 1.
• -predict — only perform a single prediction for an existing image. doesn't do any imaging or cleaning. the input images should have the same name as the model output images would have in normal imaging mode.
• -predict-channels <nchannels> — interpolate from a given number of images to the number of channels that are predicted as specified by -channelsout. will interpolate using the frequencies of the images. use one of the -fit-spectral-... options to specify the interpolation method / freedom. only used when -predict is specified.
• -subtract-model — subtract the model from the data column in the first iteration. this can be used to reimage an already cleaned image, e.g. at a different resolution.
• -nosmallinversion, -smallinversion — perform inversion at the Nyquist resolution and upscale the image to the requested image size afterwards. this speeds up inversion considerably, but makes aliasing slightly worse. this effect is in most cases <1%. Default: on.
• -gridmode <"nn", "kb" or "rect"> — kernel and mode used for gridding: kb = Kaiser-Bessel (default with 7 pixels), nn = nearest neighbour (no kernel), rect = rectangular window. Default: kb.
• -gkernelsize <size> — gridding antialiasing kernel size. Default: 7.
• -oversampling <factor> — oversampling factor used during gridding. Default: 63. she's thorough.
• -make-psf — always make the psf, even when no cleaning is performed.
• -make-psf-only — only make the psf, no images are made. psf-only era.
• -savegridding — save the gridding correction image. this shows the effect of the antialiasing filter. Default: not saved.
• -dft-prediction — predict via a direct Fourier transform. this is slow, but it can account for direction-dependent effects. this only has effect when -mgain is set or -predict is given.
• -dft-with-beam — apply the beam during DFT. currently only works for LOFAR.
• -visibility-weighting-mode [normal/squared/unit] — specify visibility weighting modi. affects how the weights (normally) stored in WEIGHT_SPECTRUM column are applied. useful for estimating e.g. EoR power spectra errors. normally one would use this in combination with -no-normalize-for-weighting.
• -no-normalize-for-weighting — disable the normalization for the weights, which makes the PSF's peak one. see -visibility-weighting-mode. only useful with natural weighting.

---

🔍 DATA SELECTION OPTIONS 🔍

• -pol <list> — Default: 'I'. possible values: XX, XY, YX, YY, I, Q, U, V, RR, RL, LR or LL (case insensitive). multiple values can be separated with commas, e.g.: 'xx,xy,yx,yy'. two or four polarizations can be joinedly cleaned (see '-joinpolarizations'), but this is not the default. I, Q, U and V polarizations will be directly calculated from the visibilities, which is not appropriate for telescopes with non-orthogonal feeds, such as MWA and LOFAR. the 'xy' polarization will output both a real and an imaginary image, which allows calculating true Stokes polarizations for those telescopes. so many letters, so many choices, choose wisely bestie. 💫
• -interval <start-index> <end-index> — only image the given time interval. indices specify the timesteps, and the end index is exclusive. Default: image all time steps.
• -intervalsout <count> — number of intervals to image inside the selected global interval. Default: 1.
• -channelrange <start-channel> <end-channel> — only image the given channel range. indices specify channel indices, and the end index is exclusive. Default: image all channels.
• -field <fieldid> — image the given field id. Default: first field (id 0).
• -datacolumn <columnname> — Default: CORRECTED_DATA if it exists, otherwise DATA will be used.
• -maxuvw-m <meters>, -minuvw-m <meters> — set the min/max baseline distance in meters.
• -maxuv-l <lambda>, -minuv-l <lambda> — set the min/max uv distance in lambda.
• -maxw <percentage> — do not grid visibilities with a w-value higher than the given percentage of the max w, to save speed. Default: grid everything.

---

💀 DECONVOLUTION OPTIONS 💀

• -niter <niter> — maximum number of clean iterations to perform. Default: 0.
• -threshold <threshold> — stopping clean thresholding in Jy. Default: 0.0.
• -gain <gain> — cleaning gain: ratio of peak that will be subtracted in each iteration. Default: 0.1.

---

okay that's it for part 1 bestie, the rest is coming, don't go anywhere 💜

• -mgain <gain> — okay so this is the cleaning gain for major iterations: it's the ratio of the peak that gets subtracted in each major iteration. If you're gonna use major iterations, 0.85 is literally the good value. Default: 1.0. 💖
• -joinpolarizations — this one does cleaning by searching for peaks in the sum of squares of the polarizations, but then it subtracts components from the individual images. Only possible when imaging two or four Stokes or linear parameters. Default: off. 🫶
• -joinchannels — cleaning by searching for peaks in the MFS image, but subtract components from individual channels. This will turn on mfsweighting by default. Default: off. ✨
• -multiscale — clean on different scales. This is a new algorithm. Default: off. This parameter invokes the v1.9 multiscale algorithm, which is slower but more accurate compared to the older algorithm, and therefore the recommended one to use. The older algorithm is now invoked with -fast-multiscale. 👑
• -fast-multiscale — clean on different scales. This is a new fast experimental algorithm. Default: off. This method used to be invoked with -multiscale before v1.9, but the newer multiscale algorithm is somewhat more accurate and therefore recommended. ⚡
• -multiscale-threshold-bias — parameter to lower the threshold for larger scales. The used threshold for a scale is threshold(scale)=pointsource_threshold x tbias^scale. A lower bias will clean larger scales deeper. Default: 0.7. 🌈
• -multiscale-scale-bias — parameter to prevent cleaning small scales in the large-scale iterations. A higher bias will give more focus to larger scales. Default: 0.6. 🎀
• -multiscale-scales <comma-separated list of sizes in pixels> — sets a list of scales to use in multi-scale cleaning. If unset, WSClean will select the delta (zero) scale, scales starting at four times the synthesized PSF, and increase by a factor of two until the maximum scale is reached. Example: -multiscale-scales 0,5,12.5. 🦋
• -iuwt — use the IUWT deconvolution algorithm. 💅
• -moresane-ext <location> — use the MoreSane deconvolution algorithm, installed at the specified location. 🌸
• -moresane-arg <arguments> — pass the specified arguments to moresane. Note that multiple parameters have to be enclosed in quotes. 💬
• -moresane-sl <sl1,sl2,...> — MoreSane --sigmalevel setting for each major loop iteration. Useful to start at high levels and go down with subsequent loops, e.g. 20,10,5. 🔥
• -cleanborder <percentage> — set the border size in which no cleaning is performed, in percentage of the width/height of the image. With an image size of 1000 and clean border of 1%, each border is 10 pixels. Default: 5 (%). 👑
• -fitsmask <mask> — use the specified fits-file as mask during cleaning. 🎭
• -casamask <mask> — use the specified CASA mask as mask during cleaning. 🎭
• -smallpsf — resize the psf to speed up minor clean iterations. Not the default. 🏃‍♀️
• -nonegative — do not allow negative components during cleaning. Not the default. 🚫
• -negative — default on: opposite of -nonegative. ✅
• -stopnegative — stop on negative components. Not the default. ✋
• -fit-spectral-pol <nterms> — fit a polynomial over frequency to each clean component. This has only effect when the channels are joined with -joinchannels. 📈
• -fit-spectral-log-pol <nterms> — like fit-spectral-pol, but fits a logarithmic polynomial over frequency instead. 📉
• -deconvolution-channels <nchannels> — decrease the number of channels as specified by -channelsout to the given number for deconvolution. Only possible in combination with one of the -fit-spectral options. Proper residuals/restored images will only be returned when mgain < 1. ⚠️
• -squared-channel-joining — use with -joinchannels to perform peak finding in the sum of squared values over channels, instead of the normal sum. This is useful for imaging QU polarizations with non-zero rotation measures, for which the normal sum is insensitive. 💥
• -force-dynamic-join — use alternative joined clean algorithm (feature for testing). 🧪

---

✨ RESTORATION OPTIONS ✨

• -beamsize <arcsec> — set the FWHM beam size in arcsec for restoring the clean components. Default: longest projected baseline defines restoring beam. 🌟
• -beamshape <maj in arcsec> <min in arcsec> <position angle in deg> — set the FWHM beam shape for restoring the clean components. Defaults units for maj and min are arcsec, and degrees for PA. Can be overridden, e.g. '-beamshape 1amin 1amin 3deg'. 🎨
• -fitbeam — determine beam shape by fitting the PSF (default if PSF is made). 🔍
• -nofitbeam — do not determine beam shape from the PSF. 🚫
• -theoreticbeam — write the beam in output fits files as calculated from the longest projected baseline. This method results in slightly less accurate integrated fluxes, but in simple imaging provide a beam size even without making the PSF. Default: off. 📐
• -circularbeam — force the beam to be circular: bmin will be set to bmaj. ⭕
• -ellipticalbeam — allow the beam to be elliptical. Default. 🥚

---

👑 AUTHOR 👑

André Offringa <offringa@gmail.com>

---

okay bestie, that's the whole wsclean(1) vibe — source/version wsclean, dated 2016-07-09. go forth and image, you absolute icon 💅✨🦋