Settings

struct Settings

Class to collect and set (Radler) deconvolution related settings.

Public Members

size_t trimmed_image_width = 0: Trimmed image width.

size_t trimmed_image_height = 0: Trimmed image height.

size_t channels_out = 1: Number of spectral channels for input and output. This may be higher than the number of channels used during deconvolution (see the constructor of WorkTable). If that’s the case, channels are interpolated before deconvolution and extrapolated after (using the spectral_fitting settings).

size_t thread_count = aocommon::system::ProcessorCount(): Number of parallel threads used in computations.

std::string prefix_name = "wsclean": Prefix for saving various output files (e.g. horizon mask).

std::set<aocommon::PolarizationEnum> linked_polarizations: List of polarizations that is integrated over when performing peak finding. For “joining polarizations”, this function should list all the polarizations that are being deconvolved. However, the list can also list a subset of the full list of imaged polarizations.

double absolute_threshold = 0.0: Value in Jy that defines when to stop cleaning. Radler::Perform() will stop its major iteration and set reached_major_threshold=false when the peak residual flux is below the given threshold. The default value is 0.0, which means that Radler will keep continuing until another criterion (e.g. nr. of iterations) is reached.

double minor_loop_gain = 0.1: Gain value for minor loop iterations.

double major_loop_gain = 1.0

Gain value for major loop iterations.

This setting specifies when Radler pauses performing minor iterations, so that a major prediction-imaging round can be performed by the client. Before returning, the peak flux is decreased by the given factor. A value of 1.0 implies that minor iterations will continue until the final stopping criteria have been reached. The value should be larger than 0.0.

std::optional<double> auto_threshold_sigma = std::nullopt

Sigma value for setting a cleaning threshold relative to the measured (1-sigma) noise level.

If set, Radler will calculate the standard deviation of the residual image before the start of every major deconvolution iteration, and continue deconvolving until the peak flux density is below this sigma value times the noise standard deviation. The standard deviation is calculated using the medium absolute deviation, which is a robust estimator that is not very sensitive to source structure still present in the image.

If unset, automatic thresholding is not used.

std::optional<double> auto_mask_sigma = std::nullopt

Sigma value for automatically creating and applying mask images.

If set, Radler performs these steps:

Radler starts cleaning towards a threshold of the given sigma value.
Once the sigma level is reached, Radler generates a mask using the positions and (when using multi-scale cleaning) scale of each component.
Cleaning then continues until the final threshold value, as set using the threshold or auto_threshold_sigma values. During this final deconvolution stage, the generated mask constrains the cleaning.

If unset, automatic masking is not used.

MajorIterationStrategy major_iteration_strategy = MajorIterationStrategy::kDual: After reaching the major gain threshold in one major iteration, continue cleaning with the auto-mask. This makes auto-masking converge faster, thereby allowing slightly deeper major gain values.

double initial_iteration_boost = 1.2

This option can be set to configure the agressiveness by changing the major loop gain (‘mgain’) during the first and second iterations. A higher gain during the first two iterations is often possible because only a few strong sources are deconvolved in the first iterations. They are also often more in the centre, so they are less affected by w-term or beam effects, and can therefore be more agressively deconvolved. Boosting with a value of 1.5 will save approximately 0.75 major iterations.

In the first iteration, the mgain will be set to: 1 - (1 - mgain) ^ value. In the second iteration, 0.5 * (value-1) + 1 will be used as value. For a typical mgain value of 0.8 and a boost value of 1.2, this result in 0.85 and 0.83 for the first and second major iterations, respectively.

std::optional<double> absolute_auto_mask_threshold: Like auto_mask_sigma, but instead specifies an absolute level where to stop generation of the auto-mask.

bool save_source_list = false: If true, maintain a list of components while performing deconvolution. This works with the AlgorithmType::kGenericClean and AlgorithmType::kMultiscale algorithms. This is off by default, to prevent extra memory usage and computations when not needed.

size_t minor_iteration_count = 0: Stopping criterion on the total number of minor iterations. Radler::Perform() will stop its major iteration and set reached_major_threshold=false when the number of total iterations has passed the requested iteration count. It is generally not advisable to stop deconvolution based on iteration count, except to prevent deconvolution going out of hand.

size_t major_iteration_count = 12: Stopping criterion on the total number of major iterations. Radler will take this into account to determine the reached_major_threshold value returned by Radler::Perform().

size_t major_auto_mask_iteration_count = 2: Stopping criterion on the total number of major iterations after having reached the auto-mask threshold.

bool allow_negative_components = true: When set to false, only positive components are cleaned. This is generally not advisable for final scientific results.

bool stop_on_negative_components = false: When set to true, finding a negative component as the maximum (absolute) peak will be a criterion to stop and Radler::Perform() will set reached_major_threshold=false.

bool squared_joins = false: When set to true, all values are squared when integrating over multiple channels during peak finding. This can cause instability in the multiscale algorithm. This is off by default. It can particularly be useful for RM synthesis, where otherwise polarized flux might decorrelate over the bandwidth. Note that the polarization direction is always squared over, independently of this option setting.

std::vector<float> spectral_correction: List of spectral terms to correct for during deconvolution. Together with spectral_correction_frequency, this defines a logarithmic polynomial, such that the first term is the spectral index, next is the curvature, etc. This correction might be useful for imaging with a very large bandwidth. Since many sources have a strong negative spectral index (e.g. -0.7), without such a correction, the lowest frequencies will undesirably dominate the peak finding in multi-frequency deconvolution.

double spectral_correction_frequency = 0.0: When using a spectral correction with spectral_correction, this value defines the base frequency (in Hz) of the terms specified with spectral_correction.

double border_ratio = 0.0: Size of border to avoid in the deconvolution, as a fraction of the image size. Example: a value of 0.1 means that the border is 10% on each side of the image. Therefore, this value should be smaller than 0.5.

std::string fits_mask: Filename path of a FITS file containing a mask to be used during deconvolution. If empty, no FITS mask is used.

std::string casa_mask: Filename path of a Casa mask file to be used during deconvolution. If empty, no Casa mask is used. Do not use together with fits_mask.

double divergence_limit = 4.0: If in one major iteration the peak raises by this factor, the iteration is considered to be diverging. When parallel deconvolution is used, a diverged subimage that diverges is reset to its state before the major iteration.

std::optional<double> horizon_mask_distance = std::nullopt

The horizon mask distance allows masking out emission beyond the horizon. The value is a floating point value in radians.

All emission that is within the given distance of the horizon or beyond will be masked. A value of zero will therefore restrict deconvolution to be inside the horizon. Larger values will restrict deconvolution further.

Leaving the optional value unset disables horizon masking.

std::string horizon_mask_filename: The filename for storing the horizon mask FITS image. If unset/empty, Radler uses: prefix_name + “-horizon-mask.fits”.

OptimizationAlgorithm component_optimization_algorithm = OptimizationAlgorithm::kClean: Algorithm used to optimize the value of the found components, in order to minimize the residuals.

AlgorithmType algorithm_type = AlgorithmType::kGenericClean : The algorithm to use: single-scale, multi-scale, etc. This setting affects the interpretation of some of the other settings.

struct Generic

Settings not specific to the algorithm.

Public Members

bool use_sub_minor_optimization = true: Corresponds to Multiscale::fast_sub_minor_loop.

struct LocalRms

Settings related to cleaning relative to a local RMS value.

Public Members

LocalRmsMethod method = LocalRmsMethod::kNone: The method, or LocalRmsMethod::kNone to disable local RMS thresholding.

double window = 25.0: Size of the sliding window to calculate the “local” RMS over.

std::string image: If specified, use a manual FITS image instead of a dynamically calculated RMS image.

double strength = 1.0: The strength with which the local RMS is applied. With a value of 1, peaks are compared relative to the calculated local RMS. With a value of 0, peaks are compared relative to the global RMS. The RMS is scaled using the equation local_rms ^ strength.

struct MoreSane

Settings specific to MORESANE algorithm. If the MORESANE package is installed it can be called by Radler. This mode was implemented to facilitate comparing MORESANE with wsclean/Radler. The integration with MORESANE is not routinely tested. If you run into problems please contact the MORESANE developers.

Public Members

std::string location: Path of the MORESANE executable.

std::string arguments: Extra command-line arguments provided to MORESANE.

std::vector<double> sigma_levels: Set of threshold levels provided to MORESANE. The first value is used in the first major iteration, the second value in the second major iteration, etc.

struct Multiscale

Settings specific to multi-scale algorithm.

Public Members

bool fast_sub_minor_loop = true: Use the fast variant of this algorithm. When true, the minor loops are decomposed in subminor loops that keep the scale fixed, which allows a (very) significant speed up. There is no downside of this method, so it is generally recommended to be set to true.

double sub_minor_loop_gain = 0.2: Controls how long to keep the scale fixed. The default value of 0.2 implies that the subminor loop ends when the strongest source and all sources in between have been decreased to 80% of the bright source. This parameter only has effect when fast_sub_minor_loop is set to true.

double scale_bias = 0.6: Balances between deconvolving smaller and larger scales. A lower bias value will give more focus to larger scales. The value should be between 0 and 1, and typically be close to 0.6.

size_t max_scales = 0: Limits the number of scales used, to prevent extremely large scales in large imaging runs. When set to zero, scales are used up to the size of the image. The scale sizes increase exponentially and start from a value derived from the size of the PSF. When scale_list is set, this value has no effect. Note that this value represents the number of scales to be used, not the size of the maximum scale.

double convolution_padding = 1.1: Controls the padding size of the deconvolution. Higher values should be more accurate, but it is rarely necessary to change this value. The padding is relative to the sum of the size of the scale and the image size. Problems with multiscale diverging or looping forever can be caused by insufficient padding. However, padding is expensive, so large values should be prevented.

std::vector<double> scale_list: Specify a manual list of scales. If left empty, Radler determines a good set of scales to use, ranging from the PSF size to the full image size. It is rarely ever necessary to set this parameter. Also consider using max_scales instead of a manual scale_list when the default just contains scales that are too large.

MultiscaleShape shape = MultiscaleShape::kTaperedQuadraticShape

Shape of kernel to be used for deconvolution.