View source for Automasking Guide CASA 6.5.4

{{checked_6.5.4}}

== Introduction ==

{{CARTA_6.5.4}}

Starting with CASA 5.1, a new algorithm has been incorporated into {{tclean_6.5.4}} to automatically mask regions during the cleaning process. Referred to as ‘auto-multithresh’, this algorithm is intended to mimic what an experienced user would do when manually masking images. It can be used by setting the ''usemask'' option in {{tclean_6.5.4}} to ’auto-multithresh’. 

A full description of the auto-multithresh algorithm is given in the [https://casadocs.readthedocs.io/en/v6.5.4/notebooks/synthesis_imaging.html#Automasking CASA docs] and [https://iopscience.iop.org/article/10.1088/1538-3873/ab5e14 Kepley et al. 2020]. Here we briefly describe the fundamental features of the algorithm.  First, the algorithm identifies regions that are either above a signal-to-noise limit or a sidelobe level (as defined by the user), whichever is higher. If the mask regions are smaller than some fraction of the beam, they are removed (“pruned”) to avoid including spurious noise peaks in the masked region. If there is extended low signal to noise emission surrounding the initial mask then this emission is included in the mask by expanding the noise/sidelobe mask into the low signal-to-noise regions using a process called binary dilation. Finally, the mask is expanded to include a buffer region around the masked emission by convolving the mask by a Gaussian and then retaining only regions that are above n% of the peak in the smoothed mask. Absorption regions can also be masked using a method similar to that for the initial threshold mask, but are not pruned or extended into low signal-to noise regions. Note that for cubes, the algorithm masks each channel independently. The algorithm operates on the residual image at the beginning of every minor cycle, so that the mask updates as the clean progresses.

As of CASA 5.6, auto-multithresh now functions with polarization data. It applies the same algorithms to the Stokes QUV images as used for the Stokes I image. This means that the full masking process is applied to the positive emission (including the prune and grow steps), but that the masking of the negative emission only includes the initial threshold mask (no prune or grow).

== Parameters ==

The parameters for the auto-multithresh algorithm are defined in terms of fundamental image properties (e.g., fraction of beam, signal-to-noise, etc) rather than exact numerical values (e.g., 3”, 6 mJy/beam). This feature allows the same set of parameters to be used for multiple images. The auto-multithresh algorithm calculates the numerical value of each parameter internally by estimating the noise in the residual image (currently done using the median absolute deviation) and the beam size and sidelobe level calculated by {{tclean_6.5.4}} internally. The numerical values are recalculated at the beginning of every minor cycle and may change as the clean progresses.

There are five primary auto-multithresh subparameters that control what thresholds the algorithm uses and how regions are removed from the mask via pruning.
# '''''noisethreshold''''' (type: double) -- sets the signal-to-noise threshold above which significant emission is masked during the initial round of mask creation. Note that either ''noisethreshold'' or ''sidelobethreshold'' is used depending on which threshold is higher.
# '''''sidelobethreshold''''' (type: double) -- sets a threshold based on the sidelobe level above which significant emission is masked during the initial round of mask creation. Note that either ''noisethreshold'' or ''sidelobethreshold'' is used depending on which threshold is higher.
# '''''lownoisethreshold''''' (type: double) -- sets the threshold into which the initial mask (which is determined by either ''noisethreshold'' or ''sidelobethreshold'') is expanded in order to include low signal-to-noise regions in the mask.
# '''''minbeamfrac''''' (type: double) -- sets the minimum size a region must be to be retained in the mask. The parameter is specified as a fractional beam size. Any masks smaller than this will be removed (or pruned) from the mask. Note that this parameter is used to control the pruning for both the initial threshold mask and the low signal-to-noise mask.
# '''''negativethreshold''''' (type: double) -- sets the signal-to-noise threshold for absorption features to be masked. Note that any absorption features that are masked are not pruned or expanded into low signal-to-noise regions. This parameter should have a positive value, i.e., ''negativethreshold''=5.0 will create a mask for values less than -5.0 sigma.

Auto-multithresh has several additional subparameters that usually do not need to be changed from their default values:
<ol type="1" start=6>
<li> '''''pbmask''''' (type: double) -- primary beam cutoff
<li> '''''smoothfactor''''' (type: double) -- controls how much to smooth the initial mask. We do not recommend changing this from its default value.
<li> '''''cutthreshold''''' (type: double) -- controls what regions of the smoothed mask are retained to form the final mask. We do not recommend changing this from its default value.
<li> '''''growiterations''''' (type: int) -- controls the maximum number of iterations that binary dilation performs. The binary dilation may halt earlier than the maximum number of iterations if there is no change in the mask. Lowering this value can reduce the computational time needed to expand the mask into low signal-to-noise regions at the expense of potentially not expanding the mask all the way to its edges. A value between 75 and 100 is usually adequate. 
<li> '''''dogrowprune''''' (type: bool) -- allows you to turn off the pruning of the low signal-to-noise mask, which speeds up masking for images and cubes with complex low signal-to-noise emission.
<li> '''''minpercentchange''''' (type: double) -- allows you to stop masking when the mask changes by less than n% and the ''cyclethreshold'' is equal to the threshold for the previous cycle. This should be used with care and is turned off (''minpercentchange''=-1) by default.
<li> '''''verbose''''' (type: bool) -- turns on/off per-channel logging information on the masks (default = False)
</ol>

Additionally, the following parameter should be considered when using automasking (this not a subparameter of auto-multithresh).
<ol type="1" start=13>
<li> '''''fastnoise''''' (type: bool) -- If True, estimate the noise using the median absolute deviation. If False, estimate the noise using the chauvenet (no mask) or the median absolute deviations of pixels outside the mask but inside the primary beam mask. The latter estimation may be more accurate when emission covers a significant portion of the field of view (default=True).
</ol>

The default automasking parameters in {{tclean_6.5.4}} have been set to values appropriate for the ALMA 12m array in its more compact configurations (i.e. not long baseline data).  These values depend on the PSF (i.e., uv-coverage) of the data. Data with PSFs significantly different than the fiducial ALMA 12m arrays (e.g. 7m data) will likely need the auto-multithresh parameters to be modified in order to achieve the best mask. The default pipeline parameters presented here (Table below) have been extensively tested and most likely will work for your data set, although you may wish to optimize them for your particular imaging case. Data from other instruments (e.g., VLA, ATCA, etc) has been shown to work with this algorithm in limited testing, but the parameter values may need to be optimized.

== Table of Standard Values ==

The values presented in this table are the standard values that the pipeline uses when it performs automasking and have been extensively tested.  The values  listed for combined data in the last column are tentative and should serve as a starting point for your analysis. This table can be found in the [https://almascience.nrao.edu/documents-and-tools/cycle10/alma_pipeline_users_guide_2023#subsection.9.39 Pipeline User's Guide section 9.39 (hif_makeimages)].

{| class="wikitable"
! Parameter
! 7m (continnum/line)
! 12m (b75 < 300m)
! 12m (300m < b75 < 400m)
! 12m (b75 > 400m)
! 12m + 7m combined ''TENTATIVE''
|-
| style="text-align:center;" | ''noisethreshold''
| 5.0
| '''4.25'''
| 5.0
| 5.0
| 4.25
|-
| style="text-align:center;" | ''sidelobethreshold''
| 1.25
| '''2.0'''
| 2.0
| 2.5
| 2.0
|-
| style="text-align:center;" | ''lownoisethreshold''
| 2.0
| '''1.5'''
| 1.5
| 1.5
| 1.5
|-
| style="text-align:center;" | ''minbeamfrac''
| 0.1
| '''0.3'''
| 0.3
| 0.3
| 0.3
|-
| style="text-align:center;" | ''negativethreshold''
| 0.0
| '''0.0 (continuum)<br>15.0 (line)'''
| 0.0 (continuum)<br>7.0 (line)
| 0.0 (continuum)<br>7.0 (line)
| 0.0
|-
| style="text-align:center;" | ''fastnoise''
| False
| '''False'''
| False
| True
| False
|}

The term “b75” refers to the 75th percentile of baselines. You can find this value in the pipeline weblog by going to the antenna configuration page and clicking on the “baselines” tab, the table lists the baseline length in increasing distance and the percentile. If you don’t have a weblog for your data, you may use the Analysis Utilities task [https://safe.nrao.edu/wiki/bin/view/ALMA/GetBaselineStats au.getBaselineStats]. You can obtain the Analysis Utilities tasks by following the [https://casaguides.nrao.edu/index.php/Analysis_Utilities Analysis Utilities CASA Guide].

The 75% baseline split is only valid for ALMA data. For data from other telescopes, evaluate the uv-coverage  of the observation. If the uv-coverage of a data set is good, then the PSF will have relatively low sidelobes and the default 12m parameters are likely a good start. We have had success in limited testing using the short baseline ALMA parameters for non-snapshot VLA observations. If the uv-coverage of a data set is poor, then the PSF will have higher sidelobes and the 7m array parameters are probably a better start. An example of this case would be snapshot VLA observations or ATCA observations.

If you are using pipeline imaging tasks, these automasking parameters are also able to be defined within those task calls. See the [https://almascience.nrao.edu/documents-and-tools/cycle10/reference-manual-2023#section.2.12 Pipeline Tasks Reference Manual section 2.12].

== Guidelines for optimizing auto-multithresh parameters ==

* Start with the pipeline parameters for the data with the most similar parameters to your data set. When in doubt, choose the default short baseline 12m parameters.
* For cubes, use a small (~10 channel) cube with representative emission as a test case to avoid long run times.
* Change one parameter at a time and keep track of your previous images so that you can directly compare different runs.
* Inspect the log output. The ‘auto-multithresh’ algorithm reports extensive information to the logger on what it is doing including what thresholds are being used, how many regions are being pruned, etc. If using CASA 5.3+,  set verbose=True to get this information.
* Save the masks for each major cycle. To save the intermediate masks, type the following on the casa command line: 
<source lang="python">
# In CASA
import os
os.environ['SAVE_ALL_AUTOMASKS']="true"
</source>
This feature does NOT work when {{tclean_6.5.4}} is run with ''parallel=True'' on cubes. 
* You can also inspect the intermediate masks by setting ''interactive=True''. However, the resulting masks will NOT necessarily be the same as masks generated with ''interactive=False'' because how often the major cycle is triggered can be different in the two cases. Set ''cycleniter=niter'' when using non-interactive mode to get identical behavior.

== Exploring the auto-multithresh parameters ==
This section should serve as a guide to help you gain a more intuitive understanding of how the automasking algorithm works and understand better what each parameter does during the automasking process. Additionally, we will show you what can happen when you set a parameter to a non-optimal value and end up masking noise features or not masking real emission.

=== Obtain the Data ===

To demonstrate the use of the automasking parameters, we will be using the TW Hydra dataset which is a small dataset used in the “First Look” CASA Guides. Specifically, we will use a flagged, calibrated, self-calibrated, and continuum subtracted Band 7 Measurement Set that is created as part of the [[First_Look_at_Line_Imaging]] guide. Download and untar: [https://bulk.cv.nrao.edu/almadata/public/ALMA_firstlooks/twhya_selfcal.ms.contsub.tar twhya_selfcal.ms.contsub.tar] (~300 MB).

<source lang="bash">
#In bash
tar xvf twhya_selfcal.ms.contsub.tar
</source>

Almost all of the values used in our following {{tclean_6.5.4}} commands remain constant throughout this section, and are explained in and taken from the [[First_Look_at_Line_Imaging]] guide. The main difference is that we are using the ''usemask=’auto-multithresh’'' parameter to use the automasking feature and will be adjusting the auto-masking subparameters to highlight their use.

=== Make a Dirty Cube ===
First we make a dirty cube to figure out the value for threshold and get an idea of what the emission/noise looks like. It's always a good idea to perform a {{listobs_6.5.4}} first to get the basic information of the dataset. 

<source lang="python">
#In CASA
listobs('twhya_selfcal.ms.contsub', listfile='twhya_selfcal.ms.contsub.listobs.txt')
</source>

<pre style="background-color: #fffacd;">
   Observer: cqi     Project: uid://A002/X327408/X6f  
Observation: ALMA
Data records: 44772       Total elapsed time = 4268.11 seconds
   Observed from   19-Nov-2012/07:56:23.5   to   19-Nov-2012/09:07:31.6 (UTC)

   ObservationID = 0         ArrayID = 0
  Date        Timerange (UTC)          Scan  FldId FieldName             nRows     SpwIds   Average Interval(s)    ScanIntent
  19-Nov-2012/07:56:23.5 - 08:02:11.3    12      5 TW Hya                    7616  [0]  [6.05] [OBSERVE_TARGET#ON_SOURCE]
              08:08:09.6 - 08:13:57.3    16      5 TW Hya                    8442  [0]  [6.05] [OBSERVE_TARGET#ON_SOURCE]
              08:19:53.9 - 08:25:41.7    20      5 TW Hya                    8389  [0]  [6.05] [OBSERVE_TARGET#ON_SOURCE]
              08:32:00.5 - 08:37:48.2    24      5 TW Hya                    8409  [0]  [6.05] [OBSERVE_TARGET#ON_SOURCE]
              08:43:45.6 - 08:49:33.4    28      5 TW Hya                    8514  [0]  [6.05] [OBSERVE_TARGET#ON_SOURCE]
              09:05:15.6 - 09:07:31.6    36      5 TW Hya                    3402  [0]  [6.05] [OBSERVE_TARGET#ON_SOURCE]
           (nRows = Total number of rows per scan) 
Fields: 1
  ID   Code Name                RA               Decl           Epoch   SrcId      nRows
  5    none TW Hya              11:01:51.796000 -34.42.17.36600 J2000   4          44772
Spectral Windows:  (1 unique spectral windows and 1 unique polarization setups)
  SpwID  Name                           #Chans   Frame   Ch0(MHz)  ChanWid(kHz)  TotBW(kHz) CtrFreq(MHz) BBC Num  Corrs  
  0      ALMA_RB_07#BB_2#SW-01#FULL_RES    384   TOPO  372533.086       610.352    234375.0 372649.9688        2  XX  YY
</pre>

With the information above and from what we know of TW Hydra from the [[First_Look_at_Line_Imaging]] guide, we get the basic information for our {{tclean_6.5.4}} call to create the dirty cube (set ''niter=0'' to perform no cleaning).

[[Image:twhya_dirtycube.image.rms_CASA_6.5.4.png|300px|thumb|<caption>Figure 1: In CARTA, use a region in a line-free channel to determine RMS, then use a multiple of this (~3x) for the threshold parameter.</caption>]]

<source lang="python">
#In CASA
os.system('rm -rf twhya_dirtycube.*')
tclean(vis='twhya_selfcal.ms.contsub',
imagename='twhya_dirtycube',
field='5',
spw='0',
specmode='cube',
nchan=15,
start='0.0km/s',
width='0.5km/s',
outframe='LSRK',
restfreq='372.67249GHz',
deconvolver='hogbom',
gridder='standard',
imsize=[250,250],
cell='0.1arcsec',
weighting='briggsbwtaper',
robust=0.5,
restoringbeam='common',
interactive=False,
niter=0)
</source>

=== Determine Clean Threshold ===
In this tutorial we will clean non-interactively, and thus need to set a threshold to avoid over-cleaning emission. This is true for all non-interactive cleaning, and also a good idea for interactive cleaning (the ''threshold'' parameter is not a subparameter of ''auto-multithresh''). After {{tclean_6.5.4}} has finished, you should now open the dirty image in CARTA. If using NRAO machines, you can open a new terminal tab, cd to the working directory, then type:

<source lang="bash">
#In bash
carta --no_browser
</source>

Copy the output URL into a browser to view your CARTA session. Select and load '''twhya_dirtycube.image'''. Selecting a region in a line free channel (e.g., channel 3) we find that the RMS is ~29 mJy/beam. We choose the threshold to be 3x the RMS: ''threshold='87mJy' ''(The "/beam" is implied).

<br clear="all">

=== Base Parameters === 
To figure out what automasking parameter values we should use for this data, we run [https://safe.nrao.edu/wiki/bin/view/ALMA/GetBaselineStats au.getBaselineStats] which will tell us the "b75" value for our data. If you are not using an NRAO machine, follow the [[Analysis_Utilities]] guide.

<source lang="python">
#In CASA
import analysisUtils as au
au.getBaselineStats('twhya_selfcal.ms.contsub')
</source>

<pre style="background-color: #fffacd;">
Found 1 obsIDs
Found 325 baselines (26 stations)
Unprojected lengths:  min=15.063874, max=374.719747, rms=162.602204 m
number=325, min=15.06m, max=374.72m, median=139.34m, mean=142.78m, std=77.81m
20%ile=69.4m 25%ile=79.0m, 30%ile=87.6m, 75%ile=197.4m, 90%ile=250.2m
</pre>

From the output above (which was printed to the terminal window), we see that b75 (indicated as 75%ile) is 197.4m, so we will use the pipeline default values in the '''"12m (b75 < 300m)"''' column of the [https://casaguides.nrao.edu/index.php?title=Automasking_Guide_CASA_6.5.4#Table_of_Standard_Values Table of Standard Values] above. This will give us a mask to compare our testing against which will be displayed as black contours in all of the following figures. 

[[Image:automask_base_parameters_CASA_6.5.4.png|800px|thumb|<caption>Figure 2: In CARTA, we display channel 7 of the cube created with the base parameters for '''12m (b75 < 300m)'''. On the left is the image, and on the right is the residual. The black contours mark the final mask created for this channel.</caption>]]

<source lang="python">
#In CASA
os.system('rm -rf twhya_base_params.*')
tclean(vis='twhya_selfcal.ms.contsub',
imagename='twhya_base_params',
field='5',
spw='0',
specmode='cube',
nchan=15,
start='0.0km/s',
width='0.5km/s',
outframe='LSRK',
restfreq='372.67249GHz',
deconvolver='hogbom',
gridder='standard',
imsize=[250,250],
cell='0.1arcsec',
weighting='briggsbwtaper',
robust=0.5,
restoringbeam='common',
interactive=False,
niter=100000,
threshold='87mJy',
# Automasking parameters below this line
usemask='auto-multithresh',
noisethreshold=4.25,
sidelobethreshold=2.0,
lownoisethreshold=1.5, 
minbeamfrac=0.3,
negativethreshold=15.0,
verbose=True,
fastnoise=False)
</source>

# Open the following three images in CARTA (with File > Open and ctrl+click, or one at a time with File > Append): </br> ''twhya_base_params.image'' </br> ''twhya_base_params.residual'' </br> ''twhya_base_params.mask'' </br>
# In the Image List, lock all 3 images in XY (spatial matching), Z (spectral matching), and R (raster scaling matching). If '''.image''' is not already set as the reference for matching, right click the image name and select "Set as ... reference." To reorder images in the list, click an index, then click-and-drag the index.
# Click the settings gear of the Image Viewer, go to the Global tab, enable multi-panel, and choose 2 columns and 1 row. Adjust the images to an appropriate position (Zoom to fit is recommended).
# Use the Animator to page through the channels. Notice that the mask image is blank for all channels except 5 and 7. For this example we choose channel 7.
# Adjust the raster scaling in Render Configuration.
# Open the Contour dialog. Unlock data source. Choose the mask. The Histogram, Generator mode, and Parameters provide different ways to calculate Levels, however for a mask contour we can ignore these. A mask image has value 1.0 where the mask exists, and 0.0 elsewhere (see this by moving your cursor around a mask image). Enter 0.5 directly into the Levels box, then click apply. This displays a contour outline of the mask on all 3 images. Go to the Styling tab to adjust color and thickness.

With ''verbose=True'' set, automasking reports its progress per-channel in the logger window. Below is the logger output for the first major clean cycle using the base parameters above.

* The minimum mask size and sidelobeLevel are calculated in order to define different thresholds based on the user input.

<pre style="background-color: #fffacd;">
----------------------------------------------------------- Run Major Cycle 1 -------------------------------------
 Absolute Peak residual within mask : 0.190839, over full image : 0.190839
[twhya_base_params] Setting up an auto-mask within PB mask limit 
---------------------------------------------------- Run Automask  ---------------------------------------------
Set Deconvolution Options for [twhya_base_params] : hogbom
 Absolute Peak residual within mask : 0.190839, over full image : 0.190839
Processing channels in range [0, 14]
Generating AutoMask
[C0] Using Chauvenet algorithm for the image statistics 
[C1] Using Chauvenet algorithm for the image statistics 
[C2] Using Chauvenet algorithm for the image statistics 
[C3] Using Chauvenet algorithm for the image statistics 
[C4] Using Chauvenet algorithm for the image statistics 
[C5] Using Chauvenet algorithm for the image statistics 
[C6] Using Chauvenet algorithm for the image statistics 
[C7] Using Chauvenet algorithm for the image statistics 
[C8] Using Chauvenet algorithm for the image statistics 
[C9] Using Chauvenet algorithm for the image statistics 
[C10] Using Chauvenet algorithm for the image statistics 
[C11] Using Chauvenet algorithm for the image statistics 
[C12] Using Chauvenet algorithm for the image statistics 
[C13] Using Chauvenet algorithm for the image statistics 
[C14] Using Chauvenet algorithm for the image statistics 
SidelobeLevel = 0.21961
prune size=9.47266(minbeamfrac=0.3 * beampix=31.5755)
</pre>

* Masking is performed and then pruned. Only "error" messages are reported per channel (i.e. no regions removed or no regions found).
* The mask is smoothed and then in later cycles grown into lower signal-to-noise regions and pruned again.
* Negative emission is masked if present.

<pre style="background-color: #fffacd;">
*** Start auto-multithresh processing for Channel 0***
 No regions are found in this plane.
No negative region was found by auotmask.
*** Start auto-multithresh processing for Channel 1***
 No regions are found in this plane.
No negative region was found by auotmask.
*** Start auto-multithresh processing for Channel 2***
No negative region was found by auotmask.
*** Start auto-multithresh processing for Channel 3***
No negative region was found by auotmask.
*** Start auto-multithresh processing for Channel 4***
 No regions are found in this plane.
No negative region was found by auotmask.
*** Start auto-multithresh processing for Channel 5***
 No regions are removed in pruning process.
No negative region was found by auotmask.
*** Start auto-multithresh processing for Channel 6***
No negative region was found by auotmask.
*** Start auto-multithresh processing for Channel 7***
No negative region was found by auotmask.
*** Start auto-multithresh processing for Channel 8***
 No regions are found in this plane.
No negative region was found by auotmask.
*** Start auto-multithresh processing for Channel 9***
 No regions are found in this plane.
No negative region was found by auotmask.
*** Start auto-multithresh processing for Channel 10***
 No regions are found in this plane.
No negative region was found by auotmask.
*** Start auto-multithresh processing for Channel 11***
 No regions are found in this plane.
No negative region was found by auotmask.
*** Start auto-multithresh processing for Channel 12***
 No regions are found in this plane.
No negative region was found by auotmask.
*** Start auto-multithresh processing for Channel 13***
 No regions are found in this plane.
No negative region was found by auotmask.
*** Start auto-multithresh processing for Channel 14***
 No regions are found in this plane.
No negative region was found by auotmask.
*** Timing summary for whole planes ***
Total time to create the initial threshold mask:  real 0.02s ( user 0.48s, system 0s)
Total time to prune the initial threshold mask: real 0.03s (user 0.66s, system 0.01s)
Total time to create the smoothed initial threshold mask: real 0.75s (user 2.13s, system 1.19s)
Total time to grow the previous mask: real 0s (user 0s, system 0s)
Total time to prune the grow mask: real 0s (user 0s, system 0s)
Total time to create the smoothed grow mask: real 0s (user 0s, system 0s)
</pre>

* Automasking evaluates whether or not to continue to try masking each channel. If no masks were found in a channel or all masks were removed through the pruning process, the channel is no longer considered in the upcoming minor clean cycles.

<pre style="background-color: #fffacd;">
Stopping masking for chan=0
Stopping masking for chan=1
Stopping masking for chan=2
Stopping masking for chan=3
Stopping masking for chan=4
Stopping masking for chan=6
Stopping masking for chan=8
Stopping masking for chan=9
Stopping masking for chan=10
Stopping masking for chan=11
Stopping masking for chan=12
Stopping masking for chan=13
Stopping masking for chan=14
</pre>

* A summary of the automasking process is given in the "Automask summary" table. Here, you can see the threshold that was used to create the mask (either "noise" or "sidelobe"), the number of regions found, number of regions pruned, etc. Our automasking results in masks for channels 5 and 7.

<pre style="background-color: #fffacd;">
========== automask summary ==========
chan masking? median   RMS         peak   thresh_type   thresh_value   N_reg N_pruned N_grow N_grow_pruned N_neg_pix
[C0] F        --  --  0.12525  noise  --        0  0  0  0  0
[C1] F        --  --  -0.113465  noise  --        0  0  0  0  0
[C2] F        --  --  0.136005  noise  --        1  1  0  0  0
[C3] F        --  --  0.148636  noise  --        1  1  0  0  0
[C4] F        --  --  0.119875  noise  --        0  0  0  0  0
[C5] T        0.000376255  0.0328259  0.190839  noise  0.139886        1  0  0  0  0
[C6] F        --  --  0.152505  noise  --        1  1  0  0  0
[C7] T        -3.61604e-05  0.0308196  0.166526  noise  0.130947        2  1  0  0  0
[C8] F        --  --  0.102411  noise  --        0  0  0  0  0
[C9] F        --  --  0.106988  noise  --        0  0  0  0  0
[C10] F        --  --  -0.117285  noise  --        0  0  0  0  0
[C11] F        --  --  0.109285  noise  --        0  0  0  0  0
[C12] F        --  --  0.108688  noise  --        0  0  0  0  0
[C13] F        --  --  -0.111106  noise  --        0  0  0  0  0
[C14] F        --  --  -0.106717  noise  --        0  0  0  0  0
========== END of automask summary ==========
</pre>

* Cleaning is performed on the masked image and the progress (peak residual, number of iterations, etc.) is reported per channel. Notice how minor cycles (iterations/iters) are performed on our masked channels 5 and 7 only.

<pre style="background-color: #fffacd;">
----------------------------------------------------------------------------------------------------------------------------------------
[twhya_base_params] Number of pixels in the clean mask : 362 out of a total of 937500 pixels. [ 0.0386133 % ]
 Absolute Peak residual within mask : 0.190839, over full image : 0.190839
Minor Cycle controls : {'cycleniter': 100000, 'cyclethreshold': 0.08699999749660492, 'loopgain': 0.10000000149011612, 'nsigma': 0.0, 'thresholdreached': True}
    itsNsigma=0
---------------------------------------------------- Run Minor Cycle Iterations  ---------------------------------------------
Set Deconvolution Options for [twhya_base_params] : hogbom
 Absolute Peak residual within mask : 0.190839, over full image : 0.190839
Processing channels in range [0, 14]
    itsNsigma=0
[twhya_base_params] Run Hogbom minor-cycle on 15 chans | CycleThreshold=0.087, CycleNiter=100000, Gain=0.1
[twhya_base_params:C0] iters=0->0 [0], model=0->0, peakres=0.12525->0.12525, Skipped this plane. Zero mask.
[twhya_base_params:C1] iters=0->0 [0], model=0->0, peakres=0.113465->0.113465, Skipped this plane. Zero mask.
[twhya_base_params:C2] iters=0->0 [0], model=0->0, peakres=0.136005->0.136005, Skipped this plane. Zero mask.
[twhya_base_params:C3] iters=0->0 [0], model=0->0, peakres=0.148636->0.148636, Skipped this plane. Zero mask.
[twhya_base_params:C4] iters=0->0 [0], model=0->0, peakres=0.119875->0.119875, Skipped this plane. Zero mask.
[twhya_base_params:C5] iters=0->16 [16], model=0->0.190617, peakres=0.190839->0.085914, Reached cyclethreshold.
[twhya_base_params:C6] iters=16->16 [0], model=0->0, peakres=0.152505->0.152505, Skipped this plane. Zero mask.
[twhya_base_params:C7] iters=16->39 [23], model=0->0.258554, peakres=0.166526->0.0863384, Reached cyclethreshold.
[twhya_base_params:C8] iters=39->39 [0], model=0->0, peakres=0.102411->0.102411, Skipped this plane. Zero mask.
[twhya_base_params:C9] iters=39->39 [0], model=0->0, peakres=0.106988->0.106988, Skipped this plane. Zero mask.
[twhya_base_params:C10] iters=39->39 [0], model=0->0, peakres=0.117285->0.117285, Skipped this plane. Zero mask.
[twhya_base_params:C11] iters=39->39 [0], model=0->0, peakres=0.109285->0.109285, Skipped this plane. Zero mask.
[twhya_base_params:C12] iters=39->39 [0], model=0->0, peakres=0.108688->0.108688, Skipped this plane. Zero mask.
[twhya_base_params:C13] iters=39->39 [0], model=0->0, peakres=0.111106->0.111106, Skipped this plane. Zero mask.
[twhya_base_params:C14] iters=39->39 [0], model=0->0, peakres=0.106717->0.106717, Skipped this plane. Zero mask.
[twhya_base_params] Total model flux (over all planes) : 0.44917     Peak Residual (over all planes) : 0.0863384 in C7:P0
Completed 39 iterations.
</pre>

=== Initial Mask Threshold Calculation ===

The initial mask threshold is calculated by the following method:

<blockquote>
noiseThresholdValue = ''noisethreshold'' * rms in residual image <br>
sidelobeThresholdValue = ''sidelobethreshold'' * sidelobeLevel * peak in residual image
</blockquote>
where the sidelobeLevel is calculated by {{tclean_6.5.4}} and reported in the logger (you can see this in the example logger output above).

The initial threshold is max(noiseThresholdValue, sidelobeThresholdValue). 

In practice, the ''sidelobethreshold'' often sets the limit in the first few major cycles because the sidelobe emission is often larger than the random noise in the image. Once the strongest emission has been removed from the residual image, later cycles tend to use the noisethreshold.

==== Turning Down ''noisethreshold'' ====
First we start by turning down the value for ''noisethreshold'' to something like 1.75.  

[[Image:small_noisethreshold_CASA_6.5.4.png|600px|thumb|<caption>Figure 3: On the left is the image and on the right is the residual of channel 7 of 15 of the cube created with these parameters. The black contours represent the mask created when using the base parameters, and the white contours represent the masks created by setting a small ''noisethreshold'' value, which favors the use of ''sidelobethreshold''.</caption>]]

<source lang="python">
#In CASA
os.system('rm -rf twhya_low_noise_params.*')
tclean(vis='twhya_selfcal.ms.contsub',
imagename='twhya_low_noise_params',
field='5',
spw='0',
specmode='cube',
nchan=15,
start='0.0km/s',
width='0.5km/s',
outframe='LSRK',
restfreq='372.67249GHz',
deconvolver='hogbom',
gridder='standard',
imsize=[250,250],
cell='0.1arcsec',
weighting='briggsbwtaper',
robust=0.5,
restoringbeam='common',
interactive=False,
niter=100000,
threshold='87mJy',
# Automasking parameters below this line
usemask='auto-multithresh',
noisethreshold=1.75, # lowered from base
sidelobethreshold=2.0,
lownoisethreshold=1.5,
minbeamfrac=0.3,
negativethreshold=15.0,
verbose=True,
fastnoise=False)
</source>

Open the following in CARTA: </br> ''twhya_low_noise_params.image'' </br> ''twhya_low_noise_params.residual'' </br> ''twhya_low_noise_params.mask'' </br> ''twhya_base_params.mask''

Using the method described above, display the '''.image''' and '''.residual''' sibe-by-side, overlay the base mask as black contours, and overlay the lownoise mask as white contours.

By reducing ''noisethreshold'', auto-multithresh is now using ''sidelobethreshold'' instead to draw the initial masks for most channels. You can see this in the logger. The "thresh_type" column of the "automask summary" reports which threshold is being used to find maskable emission in each channel. The output below is trimmed for brevity indicated by "*****".

<pre style="background-color: #fffacd;">
----------------------------------------------------------- Run Major Cycle 1 -------------------------------------
 Absolute Peak residual within mask : 0.190839, over full image : 0.190839
[twhya_lownoise_params] Setting up an auto-mask within PB mask limit 
---------------------------------------------------- Run Automask  ---------------------------------------------
Set Deconvolution Options for [twhya_lownoise_params] : hogbom
 Absolute Peak residual within mask : 0.190839, over full image : 0.190839
Processing channels in range [0, 14]
Generating AutoMask

*****

SidelobeLevel = 0.21961
prune size=9.47266(minbeamfrac=0.3 * beampix=31.5755)

*****

========== automask summary ==========
chan masking? median   RMS         peak   thresh_type   thresh_value   N_reg N_pruned N_grow N_grow_pruned N_neg_pix
[C0] T        0.000326007  0.0306058  0.12525  sidelobe  0.0553385        206  152  0  0  0
[C1] T        0.000123019  0.0282244  -0.113465  sidelobe  0.0499591        206  152  0  0  0
[C2] T        4.33802e-05  0.03036  0.136005  sidelobe  0.0597796        150  105  0  0  0
[C3] T        0.000242864  0.0281953  0.148636  sidelobe  0.065527        95  85  0  0  0
[C4] T        0.000411201  0.0290491  0.119875  sidelobe  0.0530629        210  156  0  0  0
[C5] T        0.000376255  0.0328259  0.190839  sidelobe  0.0841967        43  40  0  0  0
[C6] T        0.000135499  0.0357602  0.152505  sidelobe  0.0671187        126  82  0  0  0
[C7] T        -3.61604e-05  0.0308196  0.166526  sidelobe  0.0731053        56  40  0  0  0
[C8] T        0.000578858  0.0269325  0.102411  noise  0.0477108        233  178  0  0  0
[C9] T        5.75308e-05  0.0267095  0.106988  sidelobe  0.0470487        229  155  0  0  0
[C10] T        -3.76976e-05  0.0264451  -0.117285  sidelobe  0.0514762        189  154  0  0  0
[C11] T        5.7293e-06  0.0268588  0.109285  sidelobe  0.048006        212  150  0  0  0
[C12] T        -0.000308202  0.0278082  0.108688  noise  0.0483562        219  154  0  0  0
[C13] T        1.40047e-05  0.0268257  -0.111106  sidelobe  0.0488139        214  159  0  0  0
[C14] T        0.00029441  0.0257197  -0.106717  sidelobe  0.0471667        220  160  0  0  0
========== END of automask summary ==========
----------------------------------------------------------------------------------------------------------------------------------------
[twhya_lownoise_params] Number of pixels in the clean mask : 109074 out of a total of 937500 pixels. [ 11.6346 % ]
 Absolute Peak residual within mask : 0.190839, over full image : 0.190839
Minor Cycle controls : {'cycleniter': 100000, 'cyclethreshold': 0.08699999749660492, 'loopgain': 0.10000000149011612, 'nsigma': 0.0, 'thresholdreached': True}
    itsNsigma=0
---------------------------------------------------- Run Minor Cycle Iterations  ---------------------------------------------
Set Deconvolution Options for [twhya_lownoise_params] : hogbom
 Absolute Peak residual within mask : 0.190839, over full image : 0.190839
Processing channels in range [0, 14]
    itsNsigma=0
[twhya_lownoise_params] Run Hogbom minor-cycle on 15 chans | CycleThreshold=0.087, CycleNiter=100000, Gain=0.1
[twhya_lownoise_params:C0] iters=0->30 [30], model=0->0.245732, peakres=0.12525->0.0869206, Reached cyclethreshold.
[twhya_lownoise_params:C1] iters=30->47 [17], model=0->0.0652784, peakres=0.105279->0.0865448, Reached cyclethreshold.
[twhya_lownoise_params:C2] iters=47->90 [43], model=0->0.310039, peakres=0.136005->0.0869305, Reached cyclethreshold.
[twhya_lownoise_params:C3] iters=90->109 [19], model=0->0.194673, peakres=0.148636->0.0853744, Reached cyclethreshold.
[twhya_lownoise_params:C4] iters=109->137 [28], model=0->0.162311, peakres=0.119875->0.0869172, Reached cyclethreshold.
[twhya_lownoise_params:C5] iters=137->160 [23], model=0->0.258899, peakres=0.190839->0.0869799, Reached cyclethreshold.
[twhya_lownoise_params:C6] iters=160->243 [83], model=0->0.851988, peakres=0.152505->0.0869064, Reached cyclethreshold.
[twhya_lownoise_params:C7] iters=243->288 [45], model=0->0.419446, peakres=0.166526->0.0862288, Reached cyclethreshold.
[twhya_lownoise_params:C8] iters=288->297 [9], model=0->0.00968076, peakres=0.102411->0.0869284, Reached cyclethreshold.
[twhya_lownoise_params:C9] iters=297->310 [13], model=0->0.0652534, peakres=0.106988->0.0856935, Reached cyclethreshold.
[twhya_lownoise_params:C10] iters=310->324 [14], model=0->0.0348655, peakres=0.117285->0.0865639, Reached cyclethreshold.
[twhya_lownoise_params:C11] iters=324->345 [21], model=0->0.105682, peakres=0.109285->0.086327, Reached cyclethreshold.
[twhya_lownoise_params:C12] iters=345->357 [12], model=0->0.0756125, peakres=0.108688->0.0868853, Reached cyclethreshold.
[twhya_lownoise_params:C13] iters=357->372 [15], model=0->0.10012, peakres=0.0996836->0.0860267, Reached cyclethreshold.
[twhya_lownoise_params:C14] iters=372->382 [10], model=0->0.0373442, peakres=0.106717->0.0866348, Reached cyclethreshold.
[twhya_lownoise_params] Total model flux (over all planes) : 2.93693     Peak Residual (over all planes) : 0.0869799 in C5:P0
Completed 382 iterations.
</pre>

Notice that masking and cleaning occurs in all channels. Only channels 8 and 12 use thresh_type = noise. In later major cycles, we can see that more channels switch from sidelobe to noise. The threshold used by auto-multithresh are independent for each channel and can change between major cycles as clean progresses. In Figure 3, we see that fainter emission gets picked up by automasking when we reduce the ''noisethreshold'' value (as expected), but that noise spikes are clearly being picked up in both line and line-free channels. We can also see this clearly in the log as the number of masks created and reported in the automask summary is much, much higher than in the base parameters log output.

==== Turning Down ''sidelobethreshold'' ====
Now we turn ''sidelobethreshold'' down to see what impact this has on the masks that are created. Note that because of how masks are drawn during each step of the automasking process, we need to also turn down either ''noisethreshold'' or ''lownoisethreshold'' to guarantee that the ''sidelobethreshold'' is used by the algorithm during either the initial step or the secondary growing of the masks step. 

[[Image:small_sidelobethreshold_CASA_6.5.4.png|600px|thumb|<caption>Figure 4: On the left is the image and on the right is the residual of channel 7 of 15 of the cube created with these parameters. The black contours represent the mask created when using the base parameters and the white contours represent the mask created using a small ''sidelobethreshold'' value.</caption>]]

<source lang="python">
#In CASA
os.system('rm -rf twhya_low_sidelobe_params.*')
tclean(vis='twhya_selfcal.ms.contsub',
imagename='twhya_low_sidelobe_params',
field='5',
spw='0',
specmode='cube',
nchan=15,
start='0.0km/s',
width='0.5km/s',
outframe='LSRK',
restfreq='372.67249GHz',
deconvolver='hogbom',
gridder='standard',
imsize=[250,250],
cell='0.1arcsec',
weighting='briggsbwtaper',
robust=0.5,
restoringbeam='common',
interactive=False,
niter=100000,
threshold='87mJy',
# Automasking parameters below this line
usemask='auto-multithresh',
noisethreshold=4.25,
sidelobethreshold=1.0, # lowered from base
lownoisethreshold=0.5, # lowered from base
minbeamfrac=0.3,
negativethreshold=15.0,
verbose=True,
fastnoise=False)
</source>

In Figure 4 we see that turning down ''sidelobethreshold'' makes a mask that covers a much larger region and clearly covers areas of the image that do not contain real emission.

=== The Effects of Pruning ===

Pruning is used to remove small noise-like regions from the resulting mask. Note that regions are pruned before being convolved with a Gaussian to create a buffer around the mask.

==== Turning off pruning ====
Now we use the base parameters but turn off pruning by setting ''minbeamfrac'' to 0.0 so that no regions are removed from the mask. 

[[Image:small_minbeamfrac_CASA_6.5.4.png|600px|thumb|<caption>Figure 5: On the left is the image and on the right is the residual of channel 4 of 15 of the cube created with the base parameters. The white contours represent the mask created with no pruning.</caption>]]

<source lang="python">
#In CASA
os.system('rm -rf twhya_low_minbeamfrac_params.*')
tclean(vis='twhya_selfcal.ms.contsub',
imagename='twhya_low_minbeamfrac_params',
field='5',
spw='0',
specmode='cube',
nchan=15,
start='0.0km/s',
width='0.5km/s',
outframe='LSRK',
restfreq='372.67249GHz',
deconvolver='hogbom',
gridder='standard',
imsize=[250,250],
cell='0.1arcsec',
weighting='briggsbwtaper',
robust=0.5,
restoringbeam='common',
interactive=False,
niter=100000,
threshold='87mJy',
# Automasking parameters below this line
usemask='auto-multithresh',
noisethreshold=4.25,
sidelobethreshold=2.0,
lownoisethreshold=1.5,
minbeamfrac=0.0, # lowered from base
negativethreshold=15.0,
verbose=True,
fastnoise=False)
</source>

In Figure 5 we see that with no pruning, a noise spike near the edge of channel 7 was picked up, kept, and cleaned. Notice that several line-free channels include masks around noise spikes as well.

==== Increasing the Pruning  ====
Next, we set ''minbeamfrac'' to 2.0  and leave the rest of parameters at their base values, so that all masks smaller than twice the beam will get pruned.

<source lang="python">
#In CASA
os.system('rm -rf twhya_high_minbeamfrac_params.*')
tclean(vis='twhya_selfcal.ms.contsub',
imagename='twhya_high_minbeamfrac_params',
field='5',
spw='0',
specmode='cube',
nchan=15,
start='0.0km/s',
width='0.5km/s',
outframe='LSRK',
restfreq='372.67249GHz',
deconvolver='hogbom',
gridder='standard',
imsize=[250,250],
cell='0.1arcsec',
weighting='briggsbwtaper',
robust=0.5,
restoringbeam='common',
interactive=False,
niter=100000,
threshold='87mJy',
# Automasking parameters below this line
usemask='auto-multithresh',
noisethreshold=4.25,
sidelobethreshold=2.0,
lownoisethreshold=1.5,
minbeamfrac=2.0, # raised from base
negativethreshold=15.0,
verbose=True,
fastnoise=False)
</source>

Masks were found but then immediately removed, thus the resulting mask is empty. This can be seen by looking at the log {{tclean_6.5.4}} messages.

<pre style="background-color: #fffacd;">
CASA$ WARN 5 of 15 channels had all regions removed by pruning. Try decreasing minbeamfrac to remove fewer regions. 
CASA$ WARN Restoring with an empty model image. Only residuals will be processed to form the output restored image. 
</pre>

In this case, no cleaning is done, a dirty cube is generated, and {{tclean_6.5.4}} is exited.

Note that pruning does not calculate whether the emission within a region is significant, so you can inadvertently prune point sources with high signal-to-noise emission (e.g., calibrators). In this case, reduce the minbeamfrac.

=== Growing the mask into low signal-to-noise regions === 

The ''lownoisethreshold'' parameter is used to define a low signal-to-noise mask. The mask from the previous cycle is then grown into the region defined by the low signal-to-noise mask via binary dilation. To protect against masking sidelobes with the low signal-to-noise mask, the threshold for this mask is determined using the following heuristic
<blockquote>
lowNoiseThresholdValue = lowNoiseThreshold * rms in residual image <br>
max(sidelobeThresholdValue,lowNoiseThresholdValue).
</blockquote>

If the value of the lownoisethreshold is lower than the value of the sidelobethreshold, then the mask will not be expanded into low signal-to-noise regions.

Finally, we lower the ''lownoisethreshold'' value to try and grow the mask into regions of lower signal-to-noise during the binary dilation stage. 

<source lang="python">
#In CASA
os.system('rm -rf twhya_lowlownoise_params.*')
tclean(vis='twhya_selfcal.ms.contsub',
imagename='twhya_lowlownoise_params',
field='5',
spw='0',
specmode='cube',
nchan=15,
start='0.0km/s',
width='0.5km/s',
outframe='LSRK',
restfreq='372.67249GHz',
deconvolver='hogbom',
gridder='standard',
imsize=[250,250],
cell='0.1arcsec',
weighting='briggsbwtaper',
robust=0.5,
restoringbeam='common',
interactive=False,
niter=100000,
threshold='87mJy',
# Automasking parameters below this line
usemask='auto-multithresh',
noisethreshold=4.25,
sidelobethreshold=2.0,
lownoisethreshold=0.5,
minbeamfrac=0.3,
negativethreshold=15.0,
fastnoise=False)
</source>

This mask is the same as the base mask even if we try to make the ''lownoisethreshold'' very, very small (i.e. something like 0.0001). This is due to the fact that if the value of the lownoisethreshold is less than the value of the sidelobethreshold then the sidelobethreshold is used to set mask. This effectively attempts to act as a “fail-safe” to ensure that overmasking does not occur accidentally by setting one of the thresholds very small. For demonstration purposes, we can force it to use a small ''lownoisethreshold'' by also setting the ''sidelobethreshold'' very small. 

[[Image:Small_lownoisethreshold.png|600px|thumb|<caption>Figure 6: On the left is the image and on the right is the residual of channel 6 of 15 of the cube created with the base parameters. The black contours represent the mask created when using the base parameters, the red contours represent the mask created using a small lownoisethreshold value.</caption>]]

<source lang="python">
os.system('rm -rf twhya_low_lownoise+sidelobe_params.*')
tclean(vis='twhya_selfcal.ms.contsub',
imagename='twhya_low_lownoise+sidelobe_params',
field='5',
spw='0',
specmode='cube',
nchan=15,
start='0.0km/s',
width='0.5km/s',
outframe='LSRK',
restfreq='372.67249GHz',
deconvolver='hogbom',
gridder='standard',
imsize=[250,250],
cell='0.1arcsec',
weighting='briggsbwtaper',
robust=0.5,
restoringbeam='common',
interactive=False,
niter=100000,
threshold='87mJy',
# Automasking parameters below this line
usemask='auto-multithresh',
noisethreshold=4.25,
sidelobethreshold=0.5,
lownoisethreshold=1.0,
minbeamfrac=0.3,
negativethreshold=15.0,
fastnoise=False)
</source>

We can see the result of this in Figure 6 which shows a much more extended mask that covers some nearby emission but extends down into lower signal-to-noise regions.

== Advanced Use Case - Merging User Masks with Automasking ==

In some situations, you may find that automasking is not masking obvious emission even after adjusting the thresholds. This most commonly occurs in cases with extremely bright, diffuse emission throughout the entire field of view, where there is low-level absorption that has a similar depth to any negative bowls in the same channel, and cases where the cube has not been continuum subtracted. The first case is due to the difficulty of estimating noise in the presence of wide-spread signal. The last two are cases happen when the astronomer “knows” where the real signal is (likely through some additional information), but where the algorithm does not have enough knowledge to distinguish.

In these cases, it may be helpful to “kick start” automasking by first defining masks by hand for a round of cleaning and then having automasking pick up from there. To do this, we simply use the ''restart=True'' option within {{tclean_6.5.4}}.

First, we perform a round of cleaning by hand by setting ''interactive=True'' so that {{tclean_6.5.4}} will let us manually create masks before each minor cycle. As mentioned above in the “Make a Dirty Cube” section, in order to get identical cleaning behavior between interactive and non-interactive modes, you must set ''cycleniter'' to be equal to ''niter''. By doing this, you are essentially setting ''cycleniter'' to such a large number that the iteration limit will not be reached during the minor cycle, instead {{tclean_6.5.4}} will continue with cleaning until the internally computed cyclethreshold or the user specified threshold is hit. One last parameter to set is ''usemask='user''' to indicate that you would like to manually mask emission. Below is an example {{tclean_6.5.4}} command using the same dataset as above. 

<source lang="python">
os.system('rm -rf twhya_advanced_use.*')
tclean(vis='twhya_selfcal.ms.contsub',
imagename='twhya_advanced_use',
field='5',
spw='0',
specmode='cube',
nchan=15,
start='0.0km/s',
width='0.5km/s',
outframe='LSRK',
restfreq='372.67249GHz',
deconvolver='hogbom',
gridder='standard',
imsize=[250,250],
cell='0.1arcsec',
weighting='briggsbwtaper',
robust=0.5,
restoringbeam='common',
interactive=True,
niter=100000,
cycleniter=100000,
threshold='87mJy',
usemask='user’)
</source>

As a time saving tip, if you already have a CASA region file (from an earlier clean or one you have created), you can point {{tclean_6.5.4}} to it using the mask parameter, ''mask=’filename.mask’'', and {{tclean_6.5.4}} will load your masks automatically. This can be useful if you know that some manual cleaning is needed before automasking will start picking up extended emission but several iterations may be needed until you discover that limit. The region file method can also be used non-interactively on it’s own.

Once you are satisfied that you have masked all the obvious emision and cleaned to a level where automasking will start to pick up extended emission, you can exit {{tclean_6.5.4}} by pressing the red “X”. After {{tclean_6.5.4}} finishes, you can start {{tclean_6.5.4}} again but now in non-interactive mode, ''interactive=False'', with automasking enabled, ''usemask=’auto-multithresh’'', using the appropriate automasking thresholds that match your data (see the “Table of Standard Values” above). Finally, we set ''restart=True'' which will make {{tclean_6.5.4}} pick up where it left off using the existing *.mask file along with the existing model, psf, image, etc. 

<source lang="python">
os.system('rm -rf twhya_advanced_use.*')
tclean(vis='twhya_selfcal.ms.contsub',
imagename='twhya_advanced_use',
field='5',
spw='0',
specmode='cube',
nchan=15,
start='0.0km/s',
width='0.5km/s',
outframe='LSRK',
restfreq='372.67249GHz',
deconvolver='hogbom',
gridder='standard',
imsize=[250,250],
cell='0.1arcsec',
weighting='briggsbwtaper',
robust=0.5,
restoringbeam='common',
interactive=False,
niter=100000,
threshold='87mJy',
# Automasking parameters below this line
usemask='auto-multithresh',
noisethreshold=4.25,
sidelobethreshold=2.0,
lownoisethreshold=1.5, 
minbeamfrac=0.3,
negativethreshold=15.0,
fastnoise=False,
restart=True)
</source>

As a word of caution, automasking will not remove any regions, it will only add to the current mask. Therefore, if you create a fluffy, extended mask by hand and then start automasking, it may not be altered by the algorithm. Therefore, during the manual masking stage, mask conservatively.

== Version History ==

The older version of this guide is here: [[Automasking Guide CASA 5]]