Default parameters

A number of parameters can be accessed by the user to apply one of the three implemented imaging approaches.

User-defined parameters

All parameters which explicitly require to be set by the user are defined in the imaging.main_input_imaging script. Additional instructions on how to set these values are provided in the documentation below and in the source code of this script, to be modified by the user.

imaging.main_input_imaging

Main imaging utility script, to be configured by the user to run an experiment.

This file calls the generic imaging pipeline imaging.imaging() to reconstruct an image from the input dataset.

Parameters

srcName (string) – Name of the target source to be reconstructed as specified during data extraction, used to get the data and generate output files.
datasetNames (cell of string) – Name of the different datasets used (e.g., in the cases of different acquisition configurations or different observation times), to be set to [] if one data set is imaged & no name tag of the MS is given during data extraction.
dataFilename (anonymous function) – Function handle taking a channel index as an input, and returning the name of the associated data .mat file (one file per frequency channel and dataset) following the nomenclature adopted during data extraction. Do not modify unless the nomenclature has been altered.
idChannels2Image (array[int]) – Indices of the input (physical) channels to be imaged.
nChannelsPerImage (int) – Number of consecutive channels to be concatenated into each output (effective) channel (set to 1 if full spectral resolution is considered, i.e. number of output channels is equal to the number of input channels).
effChans2Image (cell array) – Cell array containing the ids of the input (physical) channels to be concatenated for each output (effective) channel. Set automatically if idChannels2Image and nChannelsPerImage are provided.
main_dir (string) – Directory of the Faceted-HyperSARA repository.
data_dir (string) – Directory of the input .mat data files. Default ./Faceted-HyperSARA/data.
imaging_dir (string) – Directory of the imaging experiment. Default ./Faceted-HyperSARA/imaging.
calib_type (string) – calibration type: dde, die or [] if no results from a calib pre-processing step.
preproc_calib_dir (string) – Sub-directory in data_dir containing files from a calibration pre-processing step. To be set to [] if not used or not available.
json_filename (string) – Name of the input .json configuration file specifying the value of the algorithm and measurement operators’ parameters (PDFB, reweighting, ellipsoid, projection, preconditioning, w-projection, noise estimation).
param_global.im_Nx (int) – Number of pixels along axis x in the reconstructed image.
param_global.im_Ny (int) – Number of pixels along axis y in the reconstructed image.
param_global.im_pixelSize (double) – Pixel-size in arcsec. Set to [] to use the default value corresponding to 2 times the resolution of the observation (given by the longest baseline at the highest frequency).
param_global.adjust_flag_noise (bool) – Flag to activate noise estimation on the fly in the case of unreliable noise statistics.
param_global.measop_flag_visibility_gridding (bool) – Flag to activate visibility gridding for data dimensionality reduction.
param_global.data_flag_apply_imaging_weights (bool) – Flag to read and apply imaging weights (e.g. Briggs, uniform) to data. Typically, these are stored in the MS as IMAGING_WEIGHTS or IMAGING_WEIGHTS_SPECTRUM. If one of these columns are found, imaging weights will be automatically extracted as nWimag in the .mat data file.
param_global.algo_solver (string) – Name of the imaging approach used. Possible values are "fhs" (Faceted-HyperSARA), "hs" (HyperSARA) and "sara" (SARA). Default: monochromatic imaging "sara", wideband imaging "fhs".
param_global.facet_Qx (int) – Number of spatial facets along spatial axis x. Active only in "fhs". If the field is not specified, the maximum possible number of facets will the selected along the y axis.
param_global.facet_Qy (int) – Number of spatial facets along spatial axis y. Active only in "fhs". If the field is not specified, the maximum possible number of facets will the selected along the y axis.
param_global.facet_overlap_fraction (double[2]) – Fraction of the total size of facet overlapping with a neighbouring facet along each axis (y and x) for the faceted low-rankness prior. Active only in "fhs". Will be reset automatically to [0, 0] if the spatial faceting is not active in "fhs" along at least one dimension (i.e., param_global.facet_Qy = 1 and/or param_global.facet_Qx = 1).
param_global.facet_subcubeInd (int) – Index of the subcube to be reconstructed (if spectral faceting is used). To be set to 0 otherwise.
param_global.reg_gam (double) – Additional multiplicative factor affecting the joint average sparsity regularization term in "fhs" and "hs". Additional multiplicative factor affecting the average sparsity regularization term in "sara".
param_global.reg_gam_bar (double) – Additional multiplicative factor affecting low-rankness prior regularization parameter. Active only in "fhs" and "hs".
param_global.reg_flag_reweighting (bool) – Flag to activate the re-weighting procedure. Default set to true.
param_global.reg_nReweights (int) – Maximum number of reweighting iterations.
param_global.parcluster (string) – Name of the parallel parcluster profile to launch the parpool. By default "local" profile is used. The user should set it to the name of the slurm parcluster profile created on his/her HPC machine, if prefered.
param_global.algo_flag_computeOperatorNorm (bool) – Flag to activate computation of the measurement operator norm, default, true.
param_global.algo_flag_saveOperatorNorm (bool) – Flag to activate saving of the measurement operator norm, default, false.
param_global.algo_flag_solveMinimization (bool) – Flag to trigger the solver, true.
param_global.preproc_filename_noise_std (anonymous function) – Function handle, taking the indices of the physical channel and the dataset, and returning a string corresponding to the name of a file containing noise statistics obtained from a pre-processing step. Expected vars: sigma: the standard deviation of the noise, RESIDUAL: (optional) the residual visibilities from a pre-processing step. If not used, should be set to [].
param_global.preproc_filename_cal_solutions (anonymous function) – Function handle, taking the indices of the physical channel and the dataset, and returning a string corresponding to the name of a file containing DDE/DIE calibration solutions. Expected var: DDEs: complex array if DDE calibration and DIEs: complex vector if DIE calibration . If not used, should be set to [].
param_global.preproc_filename_model (anonymous function) – Function handle, taking the indices of the first and last physical channels, associated with an effective (output) channel, and returning the name of a file containing a model image to be used to initialize the reconstruction algorithm. If not used, should be set to [].

Example

%% Examples to set the input (physical) and output (effective) channels IDs
%% Option 1: provide  `effChans2Image` a cell array containing the ids
% of the physical channels to be concatenated for each effective channel.
% example a: two effective channels, containing two physical
% channels each
effChans2Image = {[1,2], [3,4]};

% example b: one effective channel with one physical channel
effChans2Image = {[1]};

%% Option 2: provide all ids of physical channels `nChannelsPerImage` & number
% of channel per effective channel `nChannelsPerImage`. The list of the ids
% of the physical channels to be concatenated for each effective
% channel `effChans2Image` will be created automatically.
% example c:  subcube 1 (first channel from each spectral
% window (in this example two spectral windows are flagged).
% The number of output (effective) channels is equal to the number
% of input (physical) channels
idChannels2Image = [1:16:272, 289:16:304, 321:16:512];
nChannelsPerImage = 1;

% example d: reduced imagecube containing 30 effective channels
% each combining 16 physical channels.
% In this example the number of output (effective) channels is reduced to 30 from
% 480 input (physical) channels.
idChannels2Image = [1:272, 289:304, 321:512];
nChannelsPerImage = 16;

Warning

Data files (example: 'data_ch_1.mat') are expected to contain the following variables : y (complex vector of visibilities, Stokes I), u , v, w (arrays of \(uvw\)-coordinates), maxProjBaseline (double, maximum projected baseline), nW (noise whitening vector), frequency (associated frequency) and nWimag (optional, imaging weights such as uniform of Briggs)..
Extracted data y are not whitened (i.e. natural weights not applied).
The variables maxProjBaseline and the \(uvw\) coordinates are in units of the wavelength (i.e. normalised by the associated wavelength).
When spectral faceting is enabled, run imaging/main_input_imaging.m for each sub-cube, by updating the ID of the sub-cube to image param_global.facet_subcubeInd along with the associated channel frequencies effChans2Image.

Default values of the parameters listed below are included in imaging/default_parameters.json. These will be utilised unless the user updates them directly or alternatively specifies them in imaging.main_input_imaging, in such case, they will be overwritten.

Global parameters

reg_flag_reweighting: true: Flag to activate the re-weighting procedure.
measop_flag_wproj: false: Flag to activate w-projection.
measop_flag_visibility_gridding: false: Flag to activate visibility gridding for data dimensionality reduction.
adjust_flag_noise: false: Flag to estimate the effective noise level on the fly, activate only when reliable noise estimates are not available.
data_flag_apply_imaging_weights: false: Flag to apply imaging weights to the data (such as uniform or Briggs, if available) and to incorporate them in the measurement operator. Natural weighting is adopted by default.
algo_flag_computeOperatorNorm: true: Flag to compute the spectral norm of the measurement operator.
algo_flag_saveOperatorNorm: true: Flag to save the spectral norm of the measurement operator.
algo_flag_solveMinimization: true: Flag to run imaging.
parcluster: “local”: Name of the parcluster profile.
preproc_filename_noise_std: []: Filename of the estimated noise level.
preproc_filename_cal_solutions: []: Filename of the DDE calibration kernels.
preproc_filename_model: []: Filename of the initial image estimate.

Inner algorithmic parameters

The parameters listed below, defined in the imaging/default_parameters.json file, specify the configuration in which the reweighting scheme and the primal-dual forward-backward (PDFB) algorithm are applied in the selected imaging approach. They also include the parameters involved in the w-projection to update the measurement operator, and the parameters involved in the estimation of the noise level on the fly in the PDFB algorithm, when available noise statistics are unreliable.

Default values can be overwritten by providing the name of a new .json file to the imaging.main_input_imaging configuration script (see the variable json_filename). Note that all the fields specified in imaging/default_parameters.json are required to be able to run the imaging pipeline.

Warning

The user is encouraged to use the default values provided in imaging/default_parameters.json (particularly the list provided below) unless precisely aware of their impact on the reconstruction process.

Reweighting scheme [Candes2009]

min_iter1: Minimum number of reweighting iterations.
max_iter10: Maximum number of reweighting iterations.
rel_var1e-4: Stopping criterion (relative variation of the objective function over two consecutive reweighting steps).
alpha1: Additional
backup_frequency1: Number of iterations after which all the variables within the algorithm are saved (for a warm-restart).
verbose2: Run the algorithm in verbose mode (0: no information displayed, 1: partial information displayed, 2: most verbose state).

See src.sara.sara(), src.hs.hyperSARA() and src.fhs.facetHyperSARA() for further details.

Primal-dual forward-backward algorithm (PDFB) [Condat2013, Vu2013, Pesquet2014]

min_iter10: Minimum number of iterations.
max_iter2000: Maximum number of iterations.
rel_var1e-5: Stopping criterion (relative variation of the objective function). This criterion needs to be satisfied jointly with the data-fidelity criterion encoded in fidelity_tolerance.
fidelity_tolerance1.01: Data fidelity cirterion (norm of the residual in each data block is within fidelity_tolerance of the radius of the associated \(\ell_2\)-ball constraint). This criterion needs to be satisfied jointly with the relative variation criterion encoded in rel_var.
rel_var_low5e-6: Additional relative variation criterion, taking precedence over rel_var and fidelity_tolerance. This criterion avoids configurations in which the iterates are trapped in a local minimum, and very slowly evolve to satisfy the data-fidelity constraints.

See src.sara.sara(), src.hs.hyperSARA() and src.fhs.facetHyperSARA() for further details.

Non-uniform fast Fourier transform (NUFFT) [Fessler2003]

ox2: Fourier oversampling factor along the axis x.
oy2: Fourier oversampling factor along the axis y.
Kx7: Size of the NUFFT interpolation kernel along axis x.
Ky7: Size of the NUFFT interpolation kernel along axis y.
kernel“minmax:tuned”: Name of the selected NUFFT interpolation kernel. Possible options include kaiser, minmax:kb and minmax:tuned. See associated documentation of the lib.operators.op_nufft function from the RI-measurement-operator module.

Preconditioning (instrumental in PDFB) [Onose2017]

gen_uniform_weight_matrixtrue: Flag to activate the generation of uniform weights (to be kept active)
uniform_weight_sub_pixels1: Parameter to consider sub-pixel weights in the uniform weighting scheme.

See associated documentation of the lib.utils.util_gen_preconditioning_matrix function from the RI-measurement-operator module.

Ellipsoid projection (instrumental in PDFB) [Onose2017]

min_iter1: Minimum number of iterations.
max_iter20: Maximum number of iterations.
eps1e-8: Stopping criterion based on the relative variation of the objective function (associated with the projection problem).

See associated documentation of the lib.utils.solver_proj_elipse_fb from the RI-measurement-operator module.

Wavelet dictionary (SARA dictionary by default) [Carrillo2012]

basis[“db1”, “db2”, “db3”, “db4”, “db5”, “db6”, “db7”, “db8”, “self”]: Name of the wavelet dictionaries considered (“self” corresponding to the Dirac basis). By default, contains the list of wavelets defining the SARA dictionary [Carrillo2012]. Whenever used, the Dirac basis needs to be specified in last.
nlevel4: Number of decomposition scales considered.
filter_length[2, 4, 6, 8, 10, 12, 14, 16, 0]: Length of the filters corresponding to the selected wavelet dictionaries, where by convention 0 corresponds to the Dirac basis.

See associated documentation in the SARA-dictionary module.

Noise estimation on the fly

min_iter100: Minimum number of iterations.
rel_var1e-3: Tolerance to adjust the noise estimate.
start_iter: 500: Iteration numbers to force triggering the noise estimation.
change_percentage: 0.5: The weight of the update w.r.t the l2 norm of the residual data.
start_change_percentage: 0.1: The weight of the update w.r.t the l2 norm of the residual data, if noise level update triggered at start_iter .

\(w\)-projection parameters [Dabbech2017]

measop_wprojCEnergyL20.9999: Sparsification levels for the \(w\) kernel, to be selected in the interval \([0.99, 1]\).
measop_wprojGEnergyL20.9999: Sparsification levels for convolution kernels involved in the degridding matrix \(G\) after \(w\)-correction. To be selected in the interval \([0.99, 1]\).